Biblioteca cliente de certificados de Azure Key Vault para Java: versión 4.5.7

  • Artículo

Azure Key Vault permite administrar y controlar de forma segura los certificados. La biblioteca cliente de certificados de Azure Key Vault admite certificados respaldados por claves RSA y EC.

Se pueden conservar varios certificados y varias versiones del mismo certificado en el Key Vault. Las claves criptográficas de Azure Key Vault la copia de seguridad de los certificados se representan como objetos JSON Web Key (JWK). Esta biblioteca ofrece operaciones para crear, recuperar, actualizar, eliminar, purgar, realizar copias de seguridad, restaurar y enumerar los certificados, así como sus versiones.

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 en el 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 dependencias sin la etiqueta de versión, como se muestra a continuación.

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

Inclusión de dependencias directas

Si quiere 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-certificates</artifactId>
    <version>4.5.7</version>
</dependency>

Requisitos previos

Autenticar el cliente

Para interactuar con el servicio azure Key Vault, deberá crear una instancia de la CertificateClient 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][managed_identity] 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 de certificado

Una vez que realice la configuración de autenticación que mejor le convenga y reemplace su dirección URL-key-vault-url por la dirección URL del almacén de claves, puede crear :CertificateClient

CertificateClient certificateClient = new CertificateClientBuilder()
    .vaultUrl("<your-key-vault-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

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

Conceptos clave

Certificado

Azure Key Vault admite certificados con tipos de contenido secreto (PKCS12&PEM). El certificado puede estar respaldado por claves en Azure Key Vault de tipos (EC&RSA). Además de la directiva de certificado, se pueden especificar los siguientes atributos:

  • enabled: especifica si el certificado está habilitado y utilizable.
  • creado: indica cuándo se creó esta versión del certificado.
  • actualizado: indica cuándo se actualizó esta versión del certificado.

Cliente de certificado

El cliente de certificado realiza las interacciones con el servicio azure Key Vault para obtener, establecer, actualizar, eliminar y enumerar certificados y sus versiones. El cliente también admite operaciones CRUD para emisores de certificados y contactos en el almacén de claves. Los clientes asincrónicos (CertificateAsyncClient) y sincrónicos (CertificateClient) 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 certificado, puede interactuar con los tipos de recursos principales en Azure 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 del servicio Azure Key Vault Certificate, entre las que se incluyen:

Crear un certificado

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

  • beginCreateCertificatecrea un nuevo certificado en azure Key Vault. Si ya existe un certificado con el mismo nombre, se crea una nueva versión del certificado.
SyncPoller<CertificateOperation, KeyVaultCertificateWithPolicy> certificatePoller =
    certificateClient.beginCreateCertificate("certificateName", CertificatePolicy.getDefault());
certificatePoller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
KeyVaultCertificate certificate = certificatePoller.getFinalResult();
System.out.printf("Certificate created with name \"%s\"%n", certificate.getName());

Recuperación de un certificado

Recupere un certificado almacenado previamente mediante una llamada a getCertificate o getCertificateVersion.

KeyVaultCertificateWithPolicy certificate = certificateClient.getCertificate("<certificate-name>");
System.out.printf("Received certificate with name \"%s\", version %s and secret id %s%n",
    certificate.getProperties().getName(), certificate.getProperties().getVersion(), certificate.getSecretId());

Actualización de un certificado existente

Actualice un certificado existente llamando a updateCertificateProperties.

// Get the certificate to update.
KeyVaultCertificate certificate = certificateClient.getCertificate("<certificate-name>");
// Update certificate enabled status.
certificate.getProperties().setEnabled(false);
KeyVaultCertificate updatedCertificate = certificateClient.updateCertificateProperties(certificate.getProperties());
System.out.printf("Updated certificate with name \"%s\" and enabled status \"%s\"%n",
    updatedCertificate.getProperties().getName(), updatedCertificate.getProperties().isEnabled());

Eliminación de un certificado

Elimine un certificado existente llamando a beginDeleteCertificate.

SyncPoller<DeletedCertificate, Void> deleteCertificatePoller =
    certificateClient.beginDeleteCertificate("<certificate-name>");

// Deleted certificate is accessible as soon as polling beings.
PollResponse<DeletedCertificate> pollResponse = deleteCertificatePoller.poll();

// Deletion date only works for a SoftDelete-enabled Key Vault.
System.out.printf("Deleted certificate with name \"%s\" and recovery id %s", pollResponse.getValue().getName(),
    pollResponse.getValue().getRecoveryId());

// Certificate is being deleted on server.
deleteCertificatePoller.waitForCompletion();

Enumeración de certificados

Enumere los certificados en el almacén de claves mediante una llamada a listPropertiesOfCertificates.

// List operations don't return the certificates with their full information. So, for each returned certificate we call
// getCertificate to get the certificate with all its properties excluding the policy.
for (CertificateProperties certificateProperties : certificateClient.listPropertiesOfCertificates()) {
    KeyVaultCertificate certificateWithAllProperties =
        certificateClient.getCertificateVersion(certificateProperties.getName(), certificateProperties.getVersion());
    System.out.printf("Received certificate with name \"%s\" and secret id %s",
        certificateWithAllProperties.getProperties().getName(), certificateWithAllProperties.getSecretId());
}

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 del servicio Azure Key Vault Certificate, 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 subproceso principal.

Creación de un certificado de forma asincrónica

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

  • beginCreateCertificatecrea un nuevo certificado en azure Key Vault. Si ya existe un certificado con el mismo nombre, se crea una nueva versión del certificado.
// Creates a certificate using the default policy and polls on its progress.
certificateAsyncClient.beginCreateCertificate("<certificate-name>", CertificatePolicy.getDefault())
    .subscribe(pollResponse -> {
        System.out.println("---------------------------------------------------------------------------------");
        System.out.println(pollResponse.getStatus());
        System.out.println(pollResponse.getValue().getStatus());
        System.out.println(pollResponse.getValue().getStatusDetails());
    });

Recuperar un certificado de forma asincrónica

Recupere un certificado almacenado previamente mediante una llamada a getCertificate o getCertificateVersion.

certificateAsyncClient.getCertificate("<certificate-name>")
    .subscribe(certificateResponse ->
        System.out.printf("Certificate was returned with name \"%s\" and secretId %s%n",
            certificateResponse.getProperties().getName(), certificateResponse.getSecretId()));

Actualizar un certificado existente de forma asincrónica

Actualice un certificado existente llamando a updateCertificateProperties.

certificateAsyncClient.getCertificate("<certificate-name>")
    .flatMap(certificate -> {
        // Update enabled status of the certificate.
        certificate.getProperties().setEnabled(false);
        return certificateAsyncClient.updateCertificateProperties(certificate.getProperties());
    }).subscribe(certificateResponse -> System.out.printf("Certificate's enabled status: %s%n",
        certificateResponse.getProperties().isEnabled()));

Eliminar un certificado de forma asincrónica

Elimine un certificado existente llamando a beginDeleteCertificate.

certificateAsyncClient.beginDeleteCertificate("<certificate-name>")
    .subscribe(pollResponse -> {
        System.out.printf("Deletion status: %s%n", pollResponse.getStatus());
        System.out.printf("Deleted certificate name: %s%n", pollResponse.getValue().getName());
        System.out.printf("Certificate deletion date: %s%n", pollResponse.getValue().getDeletedOn());
    });

Enumeración de certificados de forma asincrónica

Enumere los certificados de Azure Key Vault mediante una llamada a listPropertiesOfCertificates.

// The List Certificates operation returns certificates without their full properties, so for each certificate returned
// we call `getCertificate` to get all its attributes excluding the policy.
certificateAsyncClient.listPropertiesOfCertificates()
    .flatMap(certificateProperties -> certificateAsyncClient
        .getCertificateVersion(certificateProperties.getName(), certificateProperties.getVersion()))
    .subscribe(certificateResponse ->
        System.out.printf("Received certificate with name \"%s\" and key id %s", certificateResponse.getName(),
            certificateResponse.getKeyId()));

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 de Certificado de Azure Key Vault generan excepciones. Por ejemplo, si intenta recuperar un certificado una vez eliminado 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 {
    certificateClient.getCertificate("<deleted-certificate-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 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