Biblioteca cliente secreta de Azure Key Vault para Java, versión 4.7.1

  • Artículo

Azure Key Vault es un servicio en la nube que proporciona almacenamiento seguro para secretos, como contraseñas y cadenas de conexión de base de datos.

La biblioteca cliente secretos de Azure Key Vault permite almacenar y controlar de forma segura el acceso a tokens, contraseñas, claves de API y otros secretos. Esta biblioteca ofrece operaciones para crear, recuperar, actualizar, eliminar, purgar, realizar copias de seguridad, restaurar y enumerar los secretos y sus versiones.

Use la biblioteca cliente secretos de Azure Key Vault para crear y administrar secretos.

Código fuente | Documentación de referencia de API | Documentación del producto | Ejemplos

Introducción

Inclusión del paquete

Inclusión del archivo BOM

Incluya al azure-sdk-bom proyecto para que dependa de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte el archivo Léame bom del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, a continuación, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión, como se muestra a continuación.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-security-keyvault-secrets</artifactId>
    </dependency>
</dependencies>

Inclusión de dependencias directas

Si desea depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-keyvault-secrets</artifactId>
    <version>4.7.1</version>
</dependency>

Requisitos previos

Autenticar el cliente

Para interactuar con el servicio azure Key Vault, deberá crear una instancia de la SecretClient clase, una dirección URL del almacén y un objeto de credencial. Los ejemplos que se muestran en este documento usan un objeto de credencial denominado DefaultAzureCredential, que es adecuado para la mayoría de los escenarios, incluidos los entornos de desarrollo y producción locales. Además, se recomienda usar una identidad administrada para la autenticación en entornos de producción.

Puede encontrar más información sobre las distintas formas de autenticación y sus tipos de credenciales correspondientes en la documentación de Azure Identity.

Creación de un cliente secreto

Una vez que realice la configuración de autenticación que mejor se adapte a su direcciónURL de key-vault-url por la dirección URL del almacén de claves, puede crear :SecretClient

SecretClient secretClient = new SecretClientBuilder()
    .vaultUrl("<your-key-vault-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

NOTA: Para usar un cliente asincrónico, use SecretAsyncClient en lugar de SecretClient y llame a buildAsyncClient().

Conceptos clave

Secreto

Un secreto es el recurso fundamental en Azure Key Vault. Desde la perspectiva del desarrollador, las API de Key Vault aceptan y devuelven los valores de secreto como cadenas. Además los datos secretos, se pueden especificar los siguientes atributos:

  • enabled: especifica si se pueden recuperar los datos secretos.
  • notBefore: identifica la hora después de la cual el secreto estará activo.
  • expires: identifica la hora de expiración en o después de la cual no se deben recuperar los datos secretos.
  • created: indica cuándo se creó esta versión del secreto.
  • actualizado: indica cuándo se actualizó esta versión del secreto.

Cliente secreto:

El cliente secreto realiza las interacciones con el servicio Azure Key Vault para obtener, establecer, actualizar, eliminar y enumerar secretos y sus versiones. Los clientes asincrónicos (SecretAsyncClient) y sincrónicos (SecretClient) existen en el SDK, lo que permite seleccionar un cliente en función del caso de uso de una aplicación. Una vez que haya inicializado un secreto, puede interactuar con los tipos de recursos principales en Key Vault.

Ejemplos

API de sincronización

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes de Azure Key Vault Secret Service, entre las que se incluyen:

Crear un secreto

Cree un secreto que se almacenará en azure Key Vault.

  • setSecretcrea un nuevo secreto en la Key Vault de Azure. Si ya existe un secreto con el nombre especificado, se crea una nueva versión del secreto.
KeyVaultSecret secret = secretClient.setSecret("<secret-name>", "<secret-value>");
System.out.printf("Secret created with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());

Recuperación de un secreto

Recupere un secreto almacenado anteriormente mediante una llamada a getSecret.

KeyVaultSecret secret = secretClient.getSecret("<secret-name>");
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());

Actualizar un secreto existente

Actualice un secreto existente llamando a 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());

eliminar un secreto

Elimine un secreto existente mediante una llamada a 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();

Enumeración de secretos

Enumere los secretos de Azure Key Vault mediante una llamada a 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());
}

API asincrónica

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas asincrónicas más comunes de Azure Key Vault Secret Service, entre las que se incluyen:

Nota: Debe agregar System.in.read() o Thread.sleep() después de las llamadas de función en la clase o subproceso principal para permitir que las funciones o operaciones asincrónicas se ejecuten y finalicen antes de que se cierre la aplicación o el subproceso principal.

Creación de un secreto de forma asincrónica

Cree un secreto que se almacenará en azure Key Vault.

  • setSecretcrea un nuevo secreto en la Key Vault de Azure. Si ya existe un secreto con el nombre especificado, se crea una nueva versión del secreto.
secretAsyncClient.setSecret("<secret-name>", "<secret-value>")
    .subscribe(secret -> System.out.printf("Created secret with name \"%s\" and value \"%s\"%n",
        secret.getName(), secret.getValue()));

Recuperar un secreto de forma asincrónica

Recupere un secreto almacenado anteriormente mediante una llamada a getSecret.

secretAsyncClient.getSecret("<secret-name>")
    .subscribe(secret -> System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n",
        secret.getName(), secret.getValue()));

Actualizar un secreto existente de forma asincrónica

Actualice un secreto existente llamando a updateSecretProperties.

secretAsyncClient.getSecret("<secret-name>")
    .flatMap(secret -> {
        // Update the expiry time of the secret.
        secret.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(50));
        return secretAsyncClient.updateSecretProperties(secret.getProperties());
    }).subscribe(updatedSecretProperties ->
        System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.getExpiresOn()));

Eliminar un secreto de forma asincrónica

Elimine un secreto existente mediante una llamada a 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());
    });

Enumeración de secretos de forma asincrónica

Enumere los secretos de Azure Key Vault mediante una llamada a 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()
    .flatMap(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()));

Solución de problemas

Consulte nuestra guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

General

Los clientes secretos de Azure Key Vault generan excepciones. Por ejemplo, si intenta recuperar un secreto después de eliminarlo, se devuelve un 404 error, lo que indica que no se encontró el recurso. En el siguiente fragmento, el error se controla correctamente al detectar la excepción y mostrar información adicional sobre el error.

try {
    secretClient.getSecret("<deleted-secret-name>");
} catch (ResourceNotFoundException e) {
    System.out.println(e.getMessage());
}

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Biblioteca SSL predeterminada

De forma predeterminada, todas las bibliotecas cliente usan la biblioteca Boring SSL nativa de Tomcat para habilitar el rendimiento de nivel nativo para las operaciones SSL. La biblioteca SSL boring es un ARCHIVO JAR de Uber que contiene bibliotecas nativas para Linux/ macOS / Windows, y proporciona un mejor rendimiento en comparación con la implementación SSL predeterminada dentro del JDK. Para obtener más información, incluido cómo reducir el tamaño de las dependencias, consulte la sección optimización del rendimiento de la wiki.

Pasos siguientes

Hay varias Key Vault ejemplos del SDK de Java disponibles en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con Azure Key Vault.

Ejemplos de pasos siguientes

Los ejemplos se explican en detalle aquí.

Documentación adicional

Para obtener documentación más amplia sobre Azure Key Vault, consulte la documentación de referencia de api.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones