Bibliothèque de client Azure Key Vault Certificate pour Java - version 4.5.7

  • Article

Azure Key Vault vous permet de gérer et de contrôler vos certificats de manière sécurisée. La bibliothèque cliente Azure Key Vault Certificate prend en charge les certificats sauvegardés par des clés RSA et EC.

Plusieurs certificats et plusieurs versions du même certificat peuvent être conservés dans le Key Vault. Les clés de chiffrement dans Azure Key Vault qui sauvegardent les certificats sont représentées en tant qu’objets JWK (JSON Web Key). Cette bibliothèque offre des opérations pour créer, récupérer, mettre à jour, supprimer, vider, sauvegarder, restaurer et répertorier les certificats, ainsi que leurs versions.

Code source | Documentation de référence de l’API | Documentation du produit | Exemples

Prise en main

Inclure le package

Inclure le fichier de nomenclature

Incluez le azure-sdk-bom dans votre projet pour qu’il soit dépendant de la version disponibilité générale (GA) de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez LE FICHIER README DE NOMENCLATURE DU KIT DE DÉVELOPPEMENT LOGICIEL 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>

puis incluez la dépendance directe dans la section dépendances sans la balise de version comme indiqué ci-dessous.

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

Inclure une dépendance directe

Si vous souhaitez prendre la dépendance sur une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

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

Prérequis

Authentifier le client

Pour interagir avec le service Azure Key Vault, vous devez créer un instance de la CertificateClient classe, une URL de coffre et un objet d’informations d’identification. Les exemples présentés dans ce document utilisent un objet d’informations d’identification nommé DefaultAzureCredential, qui convient à la plupart des scénarios, y compris aux environnements de développement et de production locaux. En outre, nous vous recommandons d’utiliser une [identité managée][managed_identity] pour l’authentification dans les environnements de production.

Vous trouverez plus d’informations sur les différentes méthodes d’authentification et leurs types d’informations d’identification correspondants dans la documentation Azure Identity.

Créer un client de certificat

Une fois que vous avez effectué la configuration d’authentification qui vous convient le mieux et que vous avez remplacé votre-key-vault-url par l’URL de votre coffre de clés, vous pouvez créer :CertificateClient

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

REMARQUE : Pour utiliser un client asynchrone, utilisez CertificateAsyncClient au lieu de CertificateClient et appelez buildAsyncClient().

Concepts clés

Certificat

Azure Key Vault prend en charge les certificats avec des types de contenu secret (PKCS12&PEM). Le certificat peut être sauvegardé par des clés dans Azure Key Vault de types (EC&RSA). En plus de la stratégie de certificat, les attributs suivants peuvent être spécifiés :

  • enabled : spécifie si le certificat est activé et utilisable.
  • créé : indique quand cette version du certificat a été créée.
  • updated : indique quand cette version du certificat a été mise à jour.

Client de certificat

Le client de certificat effectue les interactions avec le service Azure Key Vault pour obtenir, définir, mettre à jour, supprimer et répertorier les certificats et ses versions. Le client prend également en charge les opérations CRUD pour les émetteurs de certificats et les contacts dans le coffre de clés. Il existe des clients asynchrones (CertificateAsyncClient) et synchrones (CertificateClient) dans le Kit de développement logiciel (SDK) qui permettent la sélection d’un client en fonction du cas d’usage d’une application. Une fois que vous avez initialisé un certificat, vous pouvez interagir avec les types de ressources primaires dans Azure Key Vault.

Exemples

API synchrone

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches de service Azure Key Vault Certificate les plus courantes, notamment :

Créer un certificat

Créez un certificat à stocker dans le Key Vault Azure.

  • beginCreateCertificatecrée un certificat dans le Key Vault Azure. Si un certificat portant le même nom existe déjà, une nouvelle version du certificat est créée.
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());

Récupérer un certificat

Récupérez un certificat précédemment stocké en appelant getCertificate ou 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());

Mettre à jour un certificat existant

Mettez à jour un certificat existant en appelant 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());

Supprimer un certificat

Supprimez un certificat existant en appelant 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();

Afficher la liste des certificats

Répertoriez les certificats dans le coffre de clés en appelant 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 asynchrone

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches de service asynchrones Azure Key Vault Certificate les plus courantes, notamment :

Remarque : Vous devez ajouter System.in.read() ou Thread.sleep() après les appels de fonction dans le main classe/thread pour permettre aux fonctions/opérations asynchrones de s’exécuter et de se terminer avant que le main’application/thread se termine.

Créer un certificat de manière asynchrone

Créez un certificat à stocker dans le Key Vault Azure.

  • beginCreateCertificatecrée un certificat dans le Key Vault Azure. Si un certificat portant le même nom existe déjà, une nouvelle version du certificat est créée.
// 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());
    });

Récupérer un certificat de manière asynchrone

Récupérez un certificat précédemment stocké en appelant getCertificate ou 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()));

Mettre à jour un certificat existant de manière asynchrone

Mettez à jour un certificat existant en appelant 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()));

Supprimer un certificat de manière asynchrone

Supprimez un certificat existant en appelant 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());
    });

Répertorier les certificats de manière asynchrone

Répertoriez les certificats dans le Key Vault Azure en appelant 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()));

Dépannage

Consultez notre guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Général

Les clients Azure Key Vault Certificate lèvent des exceptions. Par exemple, si vous essayez de récupérer un certificat après sa suppression, une 404 erreur est retournée, indiquant que la ressource est introuvable. Dans l’extrait suivant, l’erreur est prise en charge correctement via l’interception de l’exception et l’affichage d’informations supplémentaires sur l’erreur en question.

try {
    certificateClient.getCertificate("<deleted-certificate-name>");
} catch (ResourceNotFoundException e) {
    System.out.println(e.getMessage());
}

Client HTTP par défaut

Toutes les bibliothèques de client utilisent par défaut le client HTTP Netty. L’ajout de la dépendance ci-dessus configure automatiquement la bibliothèque de client pour utiliser le client HTTP Netty. La configuration ou la modification du client HTTP sont détaillées dans le wiki pour clients HTTP.

Bibliothèque SSL par défaut

Toutes les bibliothèques de client utilisent par défaut la bibliothèque BoringSSL Tomcat native pour permettre des performances de niveau natif pour les opérations SSL. La bibliothèque SSL Boring est un fichier JAR Uber contenant des bibliothèques natives pour Linux / macOS / Windows, et offre de meilleures performances par rapport à l’implémentation SSL par défaut dans le JDK. Pour plus d’informations, notamment sur la réduction de la taille des dépendances, consultez la section du wiki consacrée à l’optimisation des performances.

Étapes suivantes

Plusieurs exemples Key Vault sdk Java sont disponibles dans le référentiel GitHub du SDK. Ces exemples fournissent un exemple de code pour d’autres scénarios couramment rencontrés lors de l’utilisation de Key Vault.

Exemples d’étapes suivantes

Les exemples sont expliqués en détail ici.

Documentation complémentaire

Pour obtenir une documentation plus complète sur Azure Key Vault, consultez la documentation de référence sur l’API.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions