Partager via

Bibliothèque de client Azure Key Vault Secret pour Java - version 4.7.1

  • Article

Azure Key Vault est un service cloud qui fournit un stockage sécurisé pour les secrets, tels que les mots de passe et les chaînes de connexion de base de données.

La bibliothèque de client Azure Key Vault Secrets vous permet de stocker et de contrôler de manière sécurisée l’accès aux jetons, mots de passe, clés API et autres secrets. Cette bibliothèque offre des opérations pour créer, récupérer, mettre à jour, supprimer, vider, sauvegarder, restaurer et répertorier les secrets et leurs versions.

Utilisez la bibliothèque de client Azure Key Vault Secrets pour créer et gérer des secrets.

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 en disponibilité générale 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 README BOM 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-secrets</artifactId>
    </dependency>
</dependencies>

Inclure une dépendance directe

Si vous souhaitez dépendre d’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-secrets</artifactId>
    <version>4.7.1</version>
</dependency>

Prérequis

Authentifier le client

Pour interagir avec le service Azure Key Vault, vous devez créer un instance de la SecretClient 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, notamment aux environnements de développement et de production locaux. En outre, nous vous recommandons d’utiliser une identité managée 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 secret

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

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

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

Concepts clés

Secret

Un secret est la ressource fondamentale dans Azure Key Vault. Pour les développeurs, les API Key Vault acceptent et retournent des valeurs de secret sous forme de chaînes. Les attributs suivants peuvent être spécifiés en plus des données du secret :

  • enabled : spécifie si les données secrètes peuvent être récupérées.
  • notBefore : identifie l’heure après laquelle le secret sera actif.
  • expire : identifie l’heure d’expiration sur ou après laquelle les données secrètes ne doivent pas être récupérées.
  • created : indique quand cette version du secret a été créée.
  • updated : indique quand cette version du secret a été mise à jour.

Client secret :

Le client secret effectue les interactions avec le service Azure Key Vault pour obtenir, définir, mettre à jour, supprimer et répertorier les secrets et ses versions. Les clients asynchrones (SecretAsyncClient) et synchrones (SecretClient) existent dans le Kit de développement logiciel (SDK) ce qui permet de sélectionner un client en fonction du cas d’usage d’une application. Une fois que vous avez initialisé un secret, vous pouvez interagir avec les types de ressources principaux dans Key Vault.

Exemples

API synchrone

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

Créer un secret

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

  • setSecretcrée un secret dans le Key Vault Azure. Si un secret portant le nom donné existe déjà, une nouvelle version du secret est créée.
KeyVaultSecret secret = secretClient.setSecret("<secret-name>", "<secret-value>");
System.out.printf("Secret created with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());

Récupérer un secret

Récupérez un secret précédemment stocké en appelant getSecret.

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

Mettre à jour un secret existant

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

supprimer un secret

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

Afficher la liste des secrets

Répertoriez les secrets dans le Key Vault Azure en appelant 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 asynchrone

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches asynchrones azure Key Vault Secret Service 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 la fermeture de l’application/du thread main.

Créer un secret de manière asynchrone

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

  • setSecretcrée un secret dans le Key Vault Azure. Si un secret portant le nom donné existe déjà, une nouvelle version du secret est créée.
secretAsyncClient.setSecret("<secret-name>", "<secret-value>")
    .subscribe(secret -> System.out.printf("Created secret with name \"%s\" and value \"%s\"%n",
        secret.getName(), secret.getValue()));

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

Récupérez un secret précédemment stocké en appelant getSecret.

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

Mettre à jour un secret existant de façon asynchrone

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

Supprimer un secret de manière asynchrone

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

Répertorier les secrets de manière asynchrone

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

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 Secret lèvent des exceptions. Par exemple, si vous essayez de récupérer un secret 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 {
    secretClient.getSecret("<deleted-secret-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 ennuyeuse 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 d’Azure 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