See: Description
Package | Description |
---|---|
com.azure.security.keyvault.secrets |
Package containing classes for creating
SecretAsyncClient and
SecretClient to perform operations on Azure Key Vault. |
com.azure.security.keyvault.secrets.models |
Package containing classes used for representing secrets, deleted secrets and their attributes in
Azure Key Vault.
|
Azure Key Vault is a cloud service that provides secure storage for secrets, such as passwords and database connection strings.
The Azure Key Vault Secrets client library allows you to securely store and tightly control the access to tokens, passwords, API keys, and other secrets. This library offers operations to create, retrieve, update, delete, purge, backup, restore, and list the secrets and its versions.
Use the Azure Key Vault Secrets client library to create and manage secrets.
Source code | API reference documentation | Product documentation | Samples
Maven dependency for the Azure Key Vault Secrets client library. Add it to your project's POM file.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-security-keyvault-secrets</artifactId>
<version>4.3.0-beta.6</version>
</dependency>
An existing Azure Key Vault. If you need to create a Key Vault, you can use the Azure Cloud Shell to create one with this Azure CLI command. Replace <your-resource-group-name>
and <your-key-vault-name>
with your own, unique names:
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
In order to interact with the Key Vault service, you'll need to create an instance of the SecretClient class. You would need a vault url and client secret credentials (client id, client secret, tenant id) to instantiate a client object using the DefaultAzureCredential
examples shown in this document.
The DefaultAzureCredential
way of authentication by providing client secret credentials is being used in this getting started section but you can find more ways to authenticate with azure-identity.
To create/get client secret credentials you can use the Azure Portal, Azure CLI or Azure Cloud Shell
Here is an Azure Cloud Shell snippet below to
Create a service principal and configure its access to Azure resources:
az ad sp create-for-rbac -n <your-application-name> --skip-assignment
Output:
{
"appId": "generated-app-ID",
"displayName": "dummy-app-name",
"name": "http://dummy-app-name",
"password": "random-password",
"tenant": "tenant-ID"
}
export AZURE_CLIENT_ID="generated-app-ID"
export AZURE_CLIENT_SECRET="random-password"
export AZURE_TENANT_ID="tenant-ID"
az keyvault set-policy --name <your-key-vault-name> --spn $AZURE_CLIENT_ID --secret-permissions backup delete get list set
--secret-permissions: Accepted values: backup, delete, get, list, purge, recover, restore, set
az keyvault show --name <your-key-vault-name>
Once you've populated the AZURECLIENTID, AZURECLIENTSECRET, and AZURETENANTID environment variables and replaced your-key-vault-url with the URI returned above, you can create the SecretClient:
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
SecretClient secretClient = new SecretClientBuilder()
.vaultUrl("<your-key-vault-url>")
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
NOTE: For using an asynchronous client use SecretAsyncClient instead of SecretClient and call
buildAsyncClient()
A secret is the fundamental resource within Azure Key Vault. From a developer's perspective, Key Vault APIs accept and return secret values as strings. In addition to the secret data, the following attributes may be specified: * enabled: Specifies whether the secret data can be retrieved. * notBefore: Identifies the time after which the secret will be active. * expires: Identifies the expiration time on or after which the secret data should not be retrieved. * created: Indicates when this version of the secret was created. * updated: Indicates when this version of the secret was updated.
The secret client performs the interactions with the Azure Key Vault service for getting, setting, updating, deleting, and listing secrets and its versions. Asynchronous (SecretAsyncClient) and synchronous (SecretClient) clients exist in the SDK allowing for selection of a client based on an application's use case. Once you've initialized a secret, you can interact with the primary resource types in Key Vault.
The following sections provide several code snippets covering some of the most common Azure Key Vault Secret service tasks, including: - Create a secret - Retrieve a secret - Update an existing secret - Delete a secret - List secrets
Create a secret to be stored in the Azure Key Vault.
- setSecret
creates a new secret in the Azure Key Vault. If a secret with the given name already exists then a new version of the secret is created.
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;
SecretClient secretClient = new SecretClientBuilder()
.vaultUrl("<your-key-vault-url>")
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
KeyVaultSecret secret = secretClient.setSecret("<secret-name>", "<secret-value>");
System.out.printf("Secret created with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());
Retrieve a previously stored secret by calling getSecret
.
KeyVaultSecret secret = secretClient.getSecret("<secret-name>");
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());
Update an existing secret by calling updateSecretProperties
.
// Get the secret to update.
KeyVaultSecret secret = secretClient.getSecret("<secret-name>");
// Update the expiry time of the secret.
secret.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(30));
SecretProperties updatedSecretProperties = secretClient.updateSecretProperties(secret.getProperties());
System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.getExpiresOn());
Delete an existing secret by calling beginDeleteSecret
.
SyncPoller<DeletedSecret, Void> deletedSecretPoller = secretClient.beginDeleteSecret("<secret-name>");
// Deleted secret is accessible as soon as polling begins.
PollResponse<DeletedSecret> deletedSecretPollResponse = deletedSecretPoller.poll();
// Deletion date only works for a SoftDelete-enabled Key Vault.
System.out.printf("Deletion date: %s%n", deletedSecretPollResponse.getValue().getDeletedOn());
// Secret is being deleted on server.
deletedSecretPoller.waitForCompletion();
List the secrets in the Azure Key Vault by calling listPropertiesOfSecrets
.
// List operations don't return the secrets with value information. So, for each returned secret we call getSecret to
// get the secret with its value information.
for (SecretProperties secretProperties : secretClient.listPropertiesOfSecrets()) {
KeyVaultSecret secretWithValue = secretClient.getSecret(secretProperties.getName(), secretProperties.getVersion());
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secretWithValue.getName(),
secretWithValue.getValue());
}
The following sections provide several code snippets covering some of the most common asynchronous Azure Key Vault Secret Service tasks, including: - Create a secret asynchronously - Retrieve a secret asynchronously - Update an existing secret asynchronously - Delete a secret asynchronously - List secrets asynchronously
Note : You should add
System.in.read()
orThread.sleep()
after the function calls in the main class/thread to allow async functions/operations to execute and finish before the main application/thread exits.
Create a secret to be stored in the Azure Key Vault.
- setSecret
creates a new secret in the Azure Key Vault. If a secret with the given name already exists then a new version of the secret is created.
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretAsyncClient;
import com.azure.security.keyvault.secrets.models.Secret;
SecretAsyncClient secretAsyncClient = new SecretClientBuilder()
.vaultUrl("<your-key-vault-url>")
.credential(new DefaultAzureCredentialBuilder().build())
.buildAsyncClient();
secretAsyncClient.setSecret("<secret-name>", "<secret-value>")
.subscribe(secret ->
System.out.printf("Created secret with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue()));
Retrieve a previously stored secret by calling getSecret
.
secretAsyncClient.getSecret("<secret-name>")
.subscribe(secret ->
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue()));
Update an existing secret by calling updateSecretProperties
.
secretAsyncClient.getSecret("<secret-name>")
.subscribe(secret -> {
// Update the expiry time of the secret.
secret.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(50));
secretAsyncClient.updateSecretProperties(secret.getProperties())
.subscribe(updatedSecretProperties ->
System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.getExpiresOn()));
});
Delete an existing secret by calling beginDeleteSecret
.
secretAsyncClient.beginDeleteSecret("<secret-name>")
.subscribe(pollResponse -> {
System.out.printf("Deletion status: %s%n", pollResponse.getStatus());
System.out.printf("Deleted secret name: %s%n", pollResponse.getValue().getName());
System.out.printf("Deleted secret value: %s%n", pollResponse.getValue().getValue());
});
List the secrets in the Azure Key Vault by calling listPropertiesOfSecrets
.
// The List secrets operation returns secrets without their value, so for each secret returned we call `getSecret`
// to get its value as well.
secretAsyncClient.listPropertiesOfSecrets()
.subscribe(secretProperties ->
secretAsyncClient.getSecret(secretProperties.getName(), secretProperties.getVersion())
.subscribe(secretResponse ->
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secretResponse.getName(),
secretResponse.getValue())));
Azure Key Vault Secret clients raise exceptions. For example, if you try to retrieve a secret after it is deleted a 404
error is returned, indicating the resource was not found. In the following snippet, the error is handled gracefully by catching the exception and displaying additional information about the error.
try {
secretClient.getSecret("<deleted-secret-name>")
} catch (ResourceNotFoundException e) {
System.out.println(e.getMessage());
}
All client libraries by default use the Netty HTTP client. Adding the above dependency will automatically configure the client library to use the Netty HTTP client. Configuring or changing the HTTP client is detailed in the HTTP clients wiki.
All client libraries, by default, use the Tomcat-native Boring SSL library to enable native-level performance for SSL operations. The Boring SSL library is an Uber JAR containing native libraries for Linux / macOS / Windows, and provides better performance compared to the default SSL implementation within the JDK. For more information, including how to reduce the dependency size, refer to the performance tuning section of the wiki.
Several Key Vault Java SDK samples are available to you in the SDK's GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Azure Key Vault.
Samples are explained in detail here.
For more extensive documentation on Azure Key Vault, see the API reference documentation.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact
Copyright © 2021 Microsoft Corporation. All rights reserved.