Azure Key Vault Secret-Clientbibliothek für Java– Version 4.7.1

Artikel
10/21/2023

Azure Key Vault ist ein Clouddienst, der einen sicheren Speicher für Geheimnisse wie Kennwörter und Datenbankverbindungszeichenfolgen bereitstellt.

Mit der Azure Key Vault Secrets-Clientbibliothek können Sie den Zugriff auf Token, Kennwörter, API-Schlüssel und andere Geheimnisse sicher speichern und genau steuern. Diese Bibliothek bietet Vorgänge zum Erstellen, Abrufen, Aktualisieren, Löschen, Löschen, Sichern, Wiederherstellen und Auflisten der Geheimnisse und ihrer Versionen.

Verwenden Sie die Azure Key Vault Secrets-Clientbibliothek, um Geheimnisse zu erstellen und zu verwalten.

Quellcode | API-Referenzdokumentation | Produktdokumentation | Beispiele

Erste Schritte

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie die azure-sdk-bom in Ihr Projekt ein, um von der Allgemeinverfügbarkeitsversion der Bibliothek abhängig zu sein. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur BOM finden Sie in der INFODATEI FÜR AZURE SDK-STÜCKLISTEN.

<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>

und fügen Sie dann die direkte Abhängigkeit wie unten dargestellt ohne das Versionstag in den Abschnitt abhängigkeiten ein.

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

Direkte Abhängigkeiten einfügen

Wenn Sie eine Abhängigkeit von einer bestimmten Version der Bibliothek annehmen möchten, die nicht in der BoM vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

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

Voraussetzungen

Java Development Kit (JDK), Version 8 oder höher.
Ein Azure-Abonnement.
Eine vorhandene Azure Key Vault. Wenn Sie einen Schlüsseltresor erstellen müssen, können Sie dies im Azure-Portal tun, indem Sie die Schritte in diesem Dokument ausführen. Alternativ können Sie die Azure CLI verwenden, indem Sie die Schritte in diesem Dokument ausführen.

Authentifizieren des Clients

Um mit dem Azure Key Vault-Dienst zu interagieren, müssen Sie eine instance der SecretClient -Klasse, eine Tresor-URL und ein Anmeldeinformationsobjekt erstellen. Die in diesem Dokument gezeigten Beispiele verwenden ein Anmeldeinformationsobjekt namens DefaultAzureCredential, das für die meisten Szenarien geeignet ist, einschließlich lokaler Entwicklungs- und Produktionsumgebungen. Darüber hinaus wird die Verwendung einer verwalteten Identität für die Authentifizierung in Produktionsumgebungen empfohlen.

Weitere Informationen zu verschiedenen Authentifizierungsmethoden und den entsprechenden Anmeldeinformationstypen finden Sie in der Dokumentation zu Azure Identity.

Erstellen eines geheimen Clients

Nachdem Sie die für Sie am besten geeignete Authentifizierung eingerichtet und Ihre-key-vault-url durch die URL für Ihren Schlüsseltresor ersetzt haben, können Sie erstellen SecretClient:

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

HINWEIS: Für die Verwendung eines asynchronen Clients verwenden Sie SecretAsyncClient anstelle von SecretClient und rufen Sie buildAsyncClient()auf.

Wichtige Begriffe

`Secret`

Ein Geheimnis ist die grundlegende Ressource in Azure Key Vault. Aus Entwicklerperspektive akzeptieren Key Vault-APIs geheime Werte als Zeichenfolge und geben sie auch in dieser Form zurück. Zusätzlich zu den Geheimnisdaten können die folgenden Attribute angegeben werden:

enabled: Gibt an, ob die geheimen Daten abgerufen werden können.
notBefore: Gibt die Zeit an, nach der das Geheimnis aktiv ist.
expires: Gibt die Ablaufzeit an oder nach der die geheimen Daten nicht abgerufen werden sollen.
created: Gibt an, wann diese Version des Geheimnisses erstellt wurde.
aktualisiert: Gibt an, wann diese Version des Geheimnisses aktualisiert wurde.

Geheimer Client:

Der geheime Client führt die Interaktionen mit dem Azure Key Vault-Dienst zum Abrufen, Festlegen, Aktualisieren, Löschen und Auflisten von Geheimnissen und zugehörigen Versionen aus. Im SDK sind asynchrone (SecretAsyncClient) und synchrone (SecretClient) Clients vorhanden, die die Auswahl eines Clients basierend auf dem Anwendungsfall einer Anwendung ermöglichen. Nachdem Sie ein Geheimnis initialisiert haben, können Sie mit den primären Ressourcentypen in Key Vault interagieren.

Beispiele

Synchronisierungs-API

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der häufigsten Azure Key Vault Secret Service-Aufgaben behandeln, einschließlich:

Erstellen eines geheimen Schlüssels
Abrufen eines Geheimnisses
Aktualisieren eines vorhandenen Geheimnisses
Löschen eines Geheimnisses
Auflisten von Geheimnissen

Erstellen eines Geheimnisses

Erstellen Sie ein Geheimnis, das im Azure-Key Vault gespeichert werden soll.

setSecreterstellt ein neues Geheimnis im Azure-Key Vault. Wenn bereits ein Geheimnis mit dem angegebenen Namen vorhanden ist, wird eine neue Version des Geheimnisses erstellt.

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

Abrufen eines Geheimnisses

Rufen Sie ein zuvor gespeichertes Geheimnis ab, indem Sie aufrufen getSecret.

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

Aktualisieren eines vorhandenen Geheimnisses

Aktualisieren Sie ein vorhandenes Geheimnis, indem Sie aufrufen 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());

Löschen eines Geheimnisses

Löschen Sie ein vorhandenes Geheimnis, indem Sie aufrufen 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();

Auflisten geheimer Schlüssel

Listen Sie die Geheimnisse im Azure-Key Vault auf, indem Sie aufrufenlistPropertiesOfSecrets.

// 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());
}

Asynchrone API

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der häufigsten asynchronen Azure Key Vault Secret Service-Aufgaben behandeln, einschließlich:

Asynchrones Erstellen eines Geheimnisses
asynchrones Abrufen eines Geheimnisses
Asynchrones Aktualisieren eines vorhandenen Geheimnisses
Asynchrones Löschen eines Geheimnisses
Asynchrones Auflisten von Geheimnissen

Hinweis: Sie sollten oder Thread.sleep() nach den Funktionsaufrufen im Standard Klasse/Thread hinzufügenSystem.in.read(), damit asynchrone Funktionen/Vorgänge ausgeführt und abgeschlossen werden können, bevor die Standard Anwendung/Thread beendet wird.

Asynchrones Erstellen eines Geheimnisses

Erstellen Sie ein Geheimnis, das im Azure-Key Vault gespeichert werden soll.

setSecreterstellt ein neues Geheimnis im Azure-Key Vault. Wenn bereits ein Geheimnis mit dem angegebenen Namen vorhanden ist, wird eine neue Version des Geheimnisses erstellt.

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

asynchrones Abrufen eines Geheimnisses

Rufen Sie ein zuvor gespeichertes Geheimnis ab, indem Sie aufrufen getSecret.

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

Asynchrones Aktualisieren eines vorhandenen Geheimnisses

Aktualisieren Sie ein vorhandenes Geheimnis, indem Sie aufrufen 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()));

Asynchrones Löschen eines Geheimnisses

Löschen Sie ein vorhandenes Geheimnis, indem Sie aufrufen 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());
    });

Asynchrones Auflisten von Geheimnissen

Listen Sie die Geheimnisse im Azure-Key Vault auf, indem Sie aufrufenlistPropertiesOfSecrets.

// 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()));

Problembehandlung

Weitere Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung .

Allgemein

Azure Key Vault Secret Clients lösen Ausnahmen aus. Wenn Sie beispielsweise versuchen, ein Geheimnis abzurufen, nachdem es gelöscht wurde, wird ein 404 Fehler zurückgegeben, der angibt, dass die Ressource nicht gefunden wurde. Im folgenden Codeausschnitt wird der Fehler ordnungsgemäß behandelt, indem die Ausnahme abgefangen wird und zusätzliche Fehlerinformationen angezeigt werden.

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

HTTP-Standardclient

Alle Clientbibliotheken verwenden standardmäßig den Netty-HTTP-Client. Durch Hinzufügen der obigen Abhängigkeit wird die Clientbibliothek automatisch für die Verwendung des Netty-HTTP-Clients konfiguriert. Das Konfigurieren oder Ändern des HTTP-Clients wird detailliert im Wiki zu HTTP-Clients beschrieben.

SSL-Standardbibliothek

Alle Clientbibliotheken verwenden standardmäßig die Tomcat-native Boring-SSL-Bibliothek, um die Leistung auf nativer Ebene für SSL-Vorgänge zu ermöglichen. Die Boring SSL-Bibliothek ist eine Uber JAR-Datei mit nativen Bibliotheken für Linux/macOS/Windows und bietet eine bessere Leistung im Vergleich zur SSL-Standardimplementierung innerhalb des JDK. Weitere Informationen, einschließlich zur Reduzierung der Abhängigkeitsgröße, finden Sie im Abschnitt Leistungsoptimierung des Wikis.

Nächste Schritte

Mehrere Key Vault Java SDK-Beispiele stehen Ihnen im GitHub-Repository des SDK zur Verfügung. Diese Beispiele bieten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit Azure Key Vault auftreten.

Beispiele für die nächsten Schritte

Die Beispiele werden hier ausführlich erläutert.

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zu Azure Key Vault finden Sie in der API-Referenzdokumentation.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe

Freigeben über