Class SecretAsyncClient

java.lang.Object
com.azure.security.keyvault.secrets.SecretAsyncClient
public final class SecretAsyncClient extends Object
The SecretAsyncClient provides asynchronous methods to manage secrets in the Azure Key Vault. The client supports creating, retrieving, updating, deleting, purging, backing up, restoring, and listing the secrets. The client also supports listing deleted secrets for a soft-delete enabled key vault.

Getting Started

In order to interact with the Azure Key Vault service, you will need to create an instance of the SecretAsyncClient class, a vault url and a credential object.

The examples shown in this document use a credential object named DefaultAzureCredential for authentication, which is appropriate for most scenarios, including local development and production environments. Additionally, we recommend using a managed identity for authentication in production environments. You can find more information on different ways of authenticating and their corresponding credential types in the Azure Identity documentation".

Sample: Construct Asynchronous Secret Client

SecretAsyncClient secretAsyncClient = new SecretClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .vaultUrl("<your-key-vault-url>")
    .buildAsyncClient();

Create a Secret

The SecretAsyncClient can be used to create a secret in the key vault.

Code Sample:

The following code sample demonstrates how to create and store a secret in the key vault, using the setSecret(String, String) API.

secretAsyncClient.setSecret("secretName", "secretValue")
    .subscribe(secretResponse ->
        System.out.printf("Secret is created with name %s and value %s%n",
            secretResponse.getName(), secretResponse.getValue()));

Note: For the synchronous sample, refer to SecretClient.


Get a Secret

The SecretAsyncClient can be used to retrieve a secret from the key vault.

Code Sample:

The following code sample demonstrates how to synchronously retrieve a previously stored secret from the key vault, using the getSecret(String) API.

secretAsyncClient.getSecret("secretName")
    .subscribe(secretWithVersion ->
        System.out.printf("Secret is returned with name %s and value %s %n",
            secretWithVersion.getName(), secretWithVersion.getValue()));

Note: For the synchronous sample, refer to SecretClient.


Delete a Secret

The SecretAsyncClient can be used to delete a secret from the key vault.

Code Sample:

The following code sample demonstrates how to delete a secret from the key vault, using the beginDeleteSecret(String) API.

secretAsyncClient.beginDeleteSecret("secretName")
    .subscribe(pollResponse -> {
        System.out.println("Delete Status: " + pollResponse.getStatus().toString());
        System.out.println("Deleted Secret Name: " + pollResponse.getValue().getName());
        System.out.println("Deleted Secret Value: " + pollResponse.getValue().getValue());
    });

Note: For the synchronous sample, refer to SecretClient.

See Also:

  • Method Details

    • getVaultUrl

      public String getVaultUrl()
      Gets the vault endpoint url to which service requests are sent to.
      Returns:
      the vault endpoint url.

    • setSecret

      public Mono<KeyVaultSecret> setSecret(KeyVaultSecret secret)
      Adds a secret to the key vault if it does not exist. If the named secret exists, a new version of the secret is created. This operation requires the secrets/set permission.

      The expires, contentType, and notBefore values in secret are optional. If not specified, enabled is set to true by key vault.

      Code sample

      Creates a new secret which activates in one day and expires in one year. Subscribes to the call asynchronously and prints out the newly created secret details when a response is received.

      SecretProperties properties = new SecretProperties()
    .setExpiresOn(OffsetDateTime.now().plusDays(60));
KeyVaultSecret newSecret = new KeyVaultSecret("secretName", "secretValue")
    .setProperties(properties);

secretAsyncClient.setSecret(newSecret)
    .subscribe(secretResponse ->
        System.out.printf("Secret is created with name %s and value %s %n",
            secretResponse.getName(), secretResponse.getValue()));
      Parameters:
      secret - The Secret object containing information about the secret and its properties. The properties secret.name and secret.value cannot be null.
      Returns:
      A Mono containing the created secret.
      Throws:
      NullPointerException - if secret is null.
      com.azure.core.exception.ResourceModifiedException - if secret is malformed.
      com.azure.core.exception.HttpResponseException - if name or value is an empty string.

    • setSecret

      public Mono<KeyVaultSecret> setSecret(String name, String value)
      Adds a secret to the key vault if it does not exist. If the named secret exists, a new version of the secret is created. This operation requires the secrets/set permission.

      Code sample

      Creates a new secret in the key vault. Subscribes to the call asynchronously and prints out the newly created secret details when a response is received.

      secretAsyncClient.setSecret("secretName", "secretValue")
    .subscribe(secretResponse ->
        System.out.printf("Secret is created with name %s and value %s%n",
            secretResponse.getName(), secretResponse.getValue()));
      Parameters:
      name - The name of the secret. It is required and cannot be null.
      value - The value of the secret. It is required and cannot be null.
      Returns:
      A Mono containing the created secret.
      Throws:
      com.azure.core.exception.ResourceModifiedException - if invalid name or value are specified.
      com.azure.core.exception.HttpResponseException - if name or value is empty string.

    • setSecretWithResponse

      public Mono<com.azure.core.http.rest.Response<KeyVaultSecret>> setSecretWithResponse(KeyVaultSecret secret)
      Adds a secret to the key vault if it does not exist. If the named secret exists, a new version of the secret is created. This operation requires the secrets/set permission.

      The expires, contentType, and notBefore values in secret are optional. If not specified, enabled is set to true by key vault.

      Code sample

      Creates a new secret which activates in one day and expires in one year. Subscribes to the call asynchronously and prints out the newly created secret details when a response is received.

      KeyVaultSecret newSecret = new KeyVaultSecret("secretName", "secretValue").
    setProperties(new SecretProperties().setExpiresOn(OffsetDateTime.now().plusDays(60)));
secretAsyncClient.setSecretWithResponse(newSecret)
    .subscribe(secretResponse ->
        System.out.printf("Secret is created with name %s and value %s %n",
            secretResponse.getValue().getName(), secretResponse.getValue().getValue()));
      Parameters:
      secret - The Secret object containing information about the secret and its properties. The properties secret.name and secret.value cannot be null.
      Returns:
      A Mono containing a Response whose value contains the created secret.
      Throws:
      NullPointerException - if secret is null.
      com.azure.core.exception.ResourceModifiedException - if secret is malformed.
      com.azure.core.exception.HttpResponseException - if name or value is an empty string.

    • getSecret

      public Mono<KeyVaultSecret> getSecret(String name)
      Gets the latest version of the specified secret from the key vault. This operation requires the secrets/get permission.

      Code sample

      Gets latest version of the secret in the key vault. Subscribes to the call asynchronously and prints out the returned secret details when a response is received.

      secretAsyncClient.getSecret("secretName")
    .subscribe(secretWithVersion ->
        System.out.printf("Secret is returned with name %s and value %s %n",
            secretWithVersion.getName(), secretWithVersion.getValue()));
      Parameters:
      name - The name of the secret.
      Returns:
      A Mono containing the requested secret.
      Throws:
      IllegalArgumentException - If name is either null or empty.
      com.azure.core.exception.ResourceNotFoundException - When a secret with the given name doesn't exist in the vault.
      com.azure.core.exception.HttpResponseException - If the server reports an error when executing the request.

    • getSecret

      public Mono<KeyVaultSecret> getSecret(String name, String version)
      Gets the specified secret with specified version from the key vault. This operation requires the secrets/get permission.

      Code sample

      Gets a specific version of the secret in the key vault. Subscribes to the call asynchronously and prints out the returned secret details when a response is received.

      String secretVersion = "6A385B124DEF4096AF1361A85B16C204";
secretAsyncClient.getSecret("secretName", secretVersion)
    // Passing a Context is optional and useful if you want a set of data to flow through the request.
    // Otherwise, the line below can be removed.
    .contextWrite(Context.of(key1, value1, key2, value2))
    .subscribe(secretWithVersion ->
        System.out.printf("Secret is returned with name %s and value %s %n",
            secretWithVersion.getName(), secretWithVersion.getValue()));
      Parameters:
      name - The name of the secret, cannot be null.
      version - The version of the secret to retrieve. If this is an empty string or null, this call is equivalent to calling getSecret(String), with the latest version being retrieved.
      Returns:
      A Mono containing a Response whose value contains the requested secret.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - When a secret with the given name and version doesn't exist in the vault.
      IllegalArgumentException - If name is either null or empty.
      com.azure.core.exception.HttpResponseException - If the server reports an error when executing the request.

    • getSecretWithResponse

      public Mono<com.azure.core.http.rest.Response<KeyVaultSecret>> getSecretWithResponse(String name, String version)
      Gets the specified secret with specified version from the key vault. This operation requires the secrets/get permission.

      Code sample

      Gets a specific version of the secret in the key vault. Subscribes to the call asynchronously and prints out the returned secret details when a response is received.

      String secretVersion = "6A385B124DEF4096AF1361A85B16C204";
secretAsyncClient.getSecretWithResponse("secretName", secretVersion)
    // Passing a Context is optional and useful if you want a set of data to flow through the request.
    // Otherwise, the line below can be removed.
    .contextWrite(Context.of(key1, value1, key2, value2))
    .subscribe(secretWithVersion ->
        System.out.printf("Secret is returned with name %s and value %s %n",
            secretWithVersion.getValue().getName(), secretWithVersion.getValue().getValue()));
      Parameters:
      name - The name of the secret, cannot be null.
      version - The version of the secret to retrieve. If this is an empty string or null, this call is equivalent to calling getSecret(String), with the latest version being retrieved.
      Returns:
      A Mono containing a Response whose value contains the requested secret.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - When a secret with the given name and version doesn't exist in the vault.
      IllegalArgumentException - If name is either null or empty.
      com.azure.core.exception.HttpResponseException - If the server reports an error when executing the request.

    • updateSecretProperties

      public Mono<SecretProperties> updateSecretProperties(SecretProperties secretProperties)
      Updates the attributes associated with the secret. The value of the secret in the key vault cannot be changed. Only attributes populated in secretProperties are changed. Attributes not specified in the request are not changed. This operation requires the secrets/set permission.

      The secret is required and its fields name and version cannot be null.

      Code sample

      Gets latest version of the secret, changes its notBefore time, and then updates it in the Azure Key Vault. Subscribes to the call asynchronously and prints out the returned secret details when a response is received.

      secretAsyncClient.getSecret("secretName")
    .subscribe(secretResponseValue -> {
        SecretProperties secretProperties = secretResponseValue.getProperties();
        //Update the not before time of the secret.
        secretProperties.setNotBefore(OffsetDateTime.now().plusDays(50));
        secretAsyncClient.updateSecretProperties(secretProperties)
            .subscribe(secretResponse ->
                System.out.printf("Secret's updated not before time %s %n",
                    secretResponse.getNotBefore().toString()));
    });
      Parameters:
      secretProperties - The secret properties object with updated properties.
      Returns:
      A Mono containing the updated secret.
      Throws:
      NullPointerException - if secret is null.
      com.azure.core.exception.ResourceNotFoundException - when a secret with name and version doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - if name or version is an empty string.

    • updateSecretPropertiesWithResponse

      public Mono<com.azure.core.http.rest.Response<SecretProperties>> updateSecretPropertiesWithResponse(SecretProperties secretProperties)
      Updates the attributes associated with the secret. The value of the secret in the key vault cannot be changed. Only attributes populated in secretProperties are changed. Attributes not specified in the request are not changed. This operation requires the secrets/set permission.

      Code sample

      Gets latest version of the secret, changes its notBefore time, and then updates it in the Azure Key Vault. Subscribes to the call asynchronously and prints out the returned secret details when a response is received.

      secretAsyncClient.getSecret("secretName")
    .subscribe(secretResponseValue -> {
        SecretProperties secretProperties = secretResponseValue.getProperties();
        //Update the not before time of the secret.
        secretProperties.setNotBefore(OffsetDateTime.now().plusDays(50));
        secretAsyncClient.updateSecretPropertiesWithResponse(secretProperties)
            .subscribe(secretResponse ->
                System.out.printf("Secret's updated not before time %s %n",
                    secretResponse.getValue().getNotBefore().toString()));
    });

      The secret is required and its fields name and version cannot be null.

      Parameters:
      secretProperties - The secret properties object with updated properties.
      Returns:
      A Mono containing a Response whose value contains the updated secret.
      Throws:
      NullPointerException - if secret is null.
      com.azure.core.exception.ResourceNotFoundException - when a secret with name and version doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - if name or version is empty string.

    • beginDeleteSecret

      public com.azure.core.util.polling.PollerFlux<DeletedSecret, Void> beginDeleteSecret(String name)
      Deletes a secret from the key vault. If soft-delete is enabled on the key vault then the secret is placed in the deleted state and for permanent deletion, needs to be purged. Otherwise, the secret is permanently deleted. All versions of a secret are deleted. This cannot be applied to individual versions of a secret. This operation requires the secrets/delete permission.

      Code sample

      Deletes the secret in the Azure Key Vault. Subscribes to the call asynchronously and prints out the deleted secret details when a response is received.

      secretAsyncClient.beginDeleteSecret("secretName")
    .subscribe(pollResponse -> {
        System.out.println("Delete Status: " + pollResponse.getStatus().toString());
        System.out.println("Deleted Secret Name: " + pollResponse.getValue().getName());
        System.out.println("Deleted Secret Value: " + pollResponse.getValue().getValue());
    });
      Parameters:
      name - The name of the secret to be deleted.
      Returns:
      A PollerFlux to poll on and retrieve deleted secret.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - when a secret with name is empty string.

    • getDeletedSecret

      public Mono<DeletedSecret> getDeletedSecret(String name)
      Gets a secret that has been deleted for a soft-delete enabled key vault. This operation requires the secrets/list permission.

      Code sample

      Gets the deleted secret from the key vault enabled for soft-delete. Subscribes to the call asynchronously and prints out the deleted secret details when a response is received.

      secretAsyncClient.getDeletedSecret("secretName")
    .subscribe(deletedSecretResponse ->
        System.out.printf("Deleted Secret's Recovery Id %s %n", deletedSecretResponse.getRecoveryId()));
      Parameters:
      name - The name of the deleted secret.
      Returns:
      A Mono containing the deleted secret.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - when a secret with name is empty string.

    • getDeletedSecretWithResponse

      public Mono<com.azure.core.http.rest.Response<DeletedSecret>> getDeletedSecretWithResponse(String name)
      Gets a secret that has been deleted for a soft-delete enabled key vault. This operation requires the secrets/list permission.

      Code sample

      Gets the deleted secret from the key vault enabled for soft-delete. Subscribes to the call asynchronously and prints out the deleted secret details when a response is received.

      secretAsyncClient.getDeletedSecretWithResponse("secretName")
    .subscribe(deletedSecretResponse ->
        System.out.printf("Deleted Secret's Recovery Id %s %n",
            deletedSecretResponse.getValue().getRecoveryId()));
      Parameters:
      name - The name of the deleted secret.
      Returns:
      A Mono containing a Response whose value contains the deleted secret.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - when a secret with name is empty string.

    • purgeDeletedSecret

      public Mono<Void> purgeDeletedSecret(String name)
      Permanently removes a deleted secret, without the possibility of recovery. This operation can only be performed on a soft-delete enabled. This operation requires the secrets/purge permission.

      Code sample

      Purges the deleted secret from the key vault enabled for soft-delete. Subscribes to the call asynchronously and prints out the status code from the server response when a response is received.

      secretAsyncClient.purgeDeletedSecret("deletedSecretName")
    .doOnSuccess(purgeResponse ->
        System.out.println("Successfully Purged deleted Secret"))
    .subscribe();
      Parameters:
      name - The name of the secret.
      Returns:
      An empty Mono.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - when a secret with name is empty string.

    • purgeDeletedSecretWithResponse

      public Mono<com.azure.core.http.rest.Response<Void>> purgeDeletedSecretWithResponse(String name)
      Permanently removes a deleted secret, without the possibility of recovery. This operation can only be enabled on a soft-delete enabled vault. This operation requires the secrets/purge permission.

      Code sample

      Purges the deleted secret from the key vault enabled for soft-delete. Subscribes to the call asynchronously and prints out the status code from the server response when a response is received.

      secretAsyncClient.purgeDeletedSecretWithResponse("deletedSecretName")
    .subscribe(purgeResponse ->
        System.out.printf("Purge Status response %d %n", purgeResponse.getStatusCode()));
      Parameters:
      name - The name of the secret.
      Returns:
      A Mono containing a Response containing status code and HTTP headers.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - when a secret with name is empty string.

    • beginRecoverDeletedSecret

      public com.azure.core.util.polling.PollerFlux<KeyVaultSecret, Void> beginRecoverDeletedSecret(String name)
      Recovers the deleted secret in the key vault to its latest version. Can only be performed on a soft-delete enabled vault. This operation requires the secrets/recover permission.

      Code sample

      Recovers the deleted secret from the key vault enabled for soft-delete. Subscribes to the call asynchronously and prints out the recovered secret details when a response is received.

      secretAsyncClient.beginRecoverDeletedSecret("deletedSecretName")
    .subscribe(pollResponse -> {
        System.out.println("Recovery Status: " + pollResponse.getStatus().toString());
        System.out.println("Recovered Secret Name: " + pollResponse.getValue().getName());
        System.out.println("Recovered Secret Value: " + pollResponse.getValue().getValue());
    });
      Parameters:
      name - The name of the deleted secret to be recovered.
      Returns:
      A PollerFlux to poll on and retrieve the recovered secret.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - when a secret with name is empty string.

    • backupSecret

      public Mono<byte[]> backupSecret(String name)
      Requests a backup of the secret be downloaded to the client. All versions of the secret will be downloaded. This operation requires the secrets/backup permission.

      Code sample

      Backs up the secret from the key vault. Subscribes to the call asynchronously and prints out the length of the secret's backup byte array returned in the response.

      secretAsyncClient.backupSecret("secretName")
    .subscribe(secretBackupResponse ->
        System.out.printf("Secret's Backup Byte array's length %s%n", secretBackupResponse.length));
      Parameters:
      name - The name of the secret.
      Returns:
      A Mono containing the backed up secret blob.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - when a secret with name is empty string.

    • backupSecretWithResponse

      public Mono<com.azure.core.http.rest.Response<byte[]>> backupSecretWithResponse(String name)
      Requests a backup of the secret be downloaded to the client. All versions of the secret will be downloaded. This operation requires the secrets/backup permission.

      Code sample

      Backs up the secret from the key vault. Subscribes to the call asynchronously and prints out the length of the secret's backup byte array returned in the response.

      secretAsyncClient.backupSecretWithResponse("secretName")
    .subscribe(secretBackupResponse ->
        System.out.printf("Secret's Backup Byte array's length %s%n", secretBackupResponse.getValue().length));
      Parameters:
      name - The name of the secret.
      Returns:
      A Mono containing a Response whose value contains the backed up secret blob.
      Throws:
      com.azure.core.exception.ResourceNotFoundException - when a secret with name doesn't exist in the key vault.
      com.azure.core.exception.HttpResponseException - when a secret with name is empty string.

    • restoreSecretBackup

      public Mono<KeyVaultSecret> restoreSecretBackup(byte[] backup)
      Restores a backed up secret, and all its versions, to a vault. This operation requires the secrets/restore permission.

      Code sample

      Restores the secret in the key vault from its backup. Subscribes to the call asynchronously and prints out the restored secret details when a response is received.

      // Pass the secret backup byte array to the restore operation.
byte[] secretBackupByteArray = {};
secretAsyncClient.restoreSecretBackup(secretBackupByteArray)
    .subscribe(secretResponse -> System.out.printf("Restored Secret with name %s and value %s %n",
        secretResponse.getName(), secretResponse.getValue()));
      Parameters:
      backup - The backup blob associated with the secret.
      Returns:
      A Mono containing the restored secret.
      Throws:
      com.azure.core.exception.ResourceModifiedException - when backup blob is malformed.

    • restoreSecretBackupWithResponse

      public Mono<com.azure.core.http.rest.Response<KeyVaultSecret>> restoreSecretBackupWithResponse(byte[] backup)
      Restores a backed up secret, and all its versions, to a vault. This operation requires the secrets/restore permission.

      Code sample

      Restores the secret in the key vault from its backup. Subscribes to the call asynchronously and prints out the restored secret details when a response is received.

      // Pass the secret backup byte array to the restore operation.
byte[] secretBackupByteArray = {};
secretAsyncClient.restoreSecretBackupWithResponse(secretBackupByteArray)
    .subscribe(secretResponse -> System.out.printf("Restored Secret with name %s and value %s %n",
        secretResponse.getValue().getName(), secretResponse.getValue().getValue()));
      Parameters:
      backup - The backup blob associated with the secret.
      Returns:
      A Mono containing a Response whose value contains the restored secret.
      Throws:
      com.azure.core.exception.ResourceModifiedException - when backup blob is malformed.

    • listPropertiesOfSecrets

      public com.azure.core.http.rest.PagedFlux<SecretProperties> listPropertiesOfSecrets()
      Lists secrets in the key vault. Each secret returned only has its identifier and attributes populated. The secret values and their versions are not listed in the response. This operation requires the secrets/list permission.

      Code sample

      The sample below fetches the all the secret properties in the vault. For each secret retrieved, makes a call to getSecret(String, String) to get its value, and then prints it out.

      secretAsyncClient.listPropertiesOfSecrets()
    .flatMap(secretProperties -> {
        String name = secretProperties.getName();
        String version = secretProperties.getVersion();

        System.out.printf("Getting secret name: '%s', version: %s%n", name, version);
        return secretAsyncClient.getSecret(name, version);
    })
    .subscribe(secretResponse -> System.out.printf("Received secret with name %s and type %s",
        secretResponse.getName(), secretResponse.getValue()));
      Returns:
      A PagedFlux containing properties of all the secrets in the vault.

    • listDeletedSecrets

      public com.azure.core.http.rest.PagedFlux<DeletedSecret> listDeletedSecrets()
      Lists deleted secrets of the key vault if it has enabled soft-delete. This operation requires the secrets/list permission.

      Code sample

      Lists the deleted secrets in the key vault. Subscribes to the call asynchronously and prints out the recovery id of each deleted secret when a response is received.

      secretAsyncClient.listDeletedSecrets()
    .subscribe(deletedSecretResponse -> System.out.printf("Deleted Secret's Recovery Id %s %n",
        deletedSecretResponse.getRecoveryId()));
      Returns:
      A Flux containing all of the deleted secrets in the vault.

    • listPropertiesOfSecretVersions

      public com.azure.core.http.rest.PagedFlux<SecretProperties> listPropertiesOfSecretVersions(String name)
      Lists all versions of the specified secret. Each secret returned only has its identifier and attributes populated. The secret values and secret versions are not listed in the response. This operation requires the secrets/list permission.

      Code sample

      The sample below fetches the all the versions of the given secret. For each version retrieved, makes a call to getSecret(String, String) to get the version's value, and then prints it out.

      secretAsyncClient.listPropertiesOfSecretVersions("secretName")
    .flatMap(secretProperties -> {
        System.out.println("Get secret value for version: " + secretProperties.getVersion());
        return secretAsyncClient.getSecret(secretProperties.getName(), secretProperties.getVersion());
    })
    .subscribe(secret -> System.out.printf("Received secret with name %s and type %s%n",
        secret.getName(), secret.getValue()));
      Parameters:
      name - The name of the secret.
      Returns:
      A PagedFlux containing properties of all the versions of the specified secret in the vault. Flux is empty if secret with name does not exist in key vault
      Throws:
      com.azure.core.exception.HttpResponseException - when a secret with name is empty string.