Azure Key Vault-Zertifikatclientbibliothek für Java – Version 4.5.7

  • Artikel

Mit Azure Key Vault können Sie Ihre Zertifikate sicher verwalten und streng steuern. Die Azure Key Vault Certificate-Clientbibliothek unterstützt Zertifikate, die mit RSA- und EC-Schlüsseln unterstützt werden.

Mehrere Zertifikate und mehrere Versionen desselben Zertifikats können im Key Vault beibehalten werden. Kryptografische Schlüssel in Azure Key Vault, die die Zertifikate sichern, werden als JSON-Webschlüssel (JWK)-Objekte dargestellt. Diese Bibliothek bietet Vorgänge zum Erstellen, Abrufen, Aktualisieren, Löschen, Löschen, Sichern, Wiederherstellen und Auflisten der Zertifikate sowie der zugehörigen Versionen.

Quellcode | API-Referenzdokumentation | Produktdokumentation | Beispiele

Erste Schritte

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der Allgemeinverfügbarkeitsversion der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste finden Sie in der AZURE SDK-BOM-INFODATEI.

<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 in den Abschnitt abhängigkeiten ohne das Versionstag ein, wie unten gezeigt.

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

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

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

Voraussetzungen

Authentifizieren des Clients

Um mit dem Azure Key Vault-Dienst zu interagieren, müssen Sie eine instance der CertificateClient 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][managed_identity] 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 Zertifikatclients

Nachdem Sie die für Sie am besten geeignete Authentifizierungs-Einrichtung durchgeführt und Your-key-vault-url durch die URL für Ihren Schlüsseltresor ersetzt haben, können Sie folgendes CertificateClienterstellen:

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

HINWEIS: Verwenden Sie CertificateAsyncClient für die Verwendung eines asynchronen Clients anstelle von CertificateClient und aufrufen buildAsyncClient().

Wichtige Begriffe

Zertifikat

Azure Key Vault unterstützt Zertifikate mit geheimen Inhaltstypen (PKCS12&PEM). Das Zertifikat kann durch Schlüssel in Azure Key Vault vom Typ (EC&RSA) gesichert werden. Zusätzlich zur Zertifikatrichtlinie können die folgenden Attribute angegeben werden:

  • enabled: Gibt an, ob das Zertifikat aktiviert und verwendbar ist.
  • created: Gibt an, wann diese Version des Zertifikats erstellt wurde.
  • aktualisiert: Gibt an, wann diese Version des Zertifikats aktualisiert wurde.

Zertifikatclient

Der Zertifikatclient führt die Interaktionen mit dem Azure Key Vault-Dienst zum Abrufen, Festlegen, Aktualisieren, Löschen und Auflisten von Zertifikaten und zugehörigen Versionen aus. Der Client unterstützt auch CRUD-Vorgänge für Zertifikataussteller und Kontakte im Schlüsseltresor. Im SDK sind asynchrone (CertificateAsyncClient) und synchrone (CertificateClient) Clients vorhanden, die die Auswahl eines Clients basierend auf dem Anwendungsfall einer Anwendung ermöglichen. Nachdem Sie ein Zertifikat initialisiert haben, können Sie mit den primären Ressourcentypen in Azure Key Vault interagieren.

Beispiele

Synchronisierungs-API

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

Erstellen eines Zertifikats

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

  • beginCreateCertificateerstellt ein neues Zertifikat im Azure-Key Vault. Wenn bereits ein Zertifikat mit demselben Namen vorhanden ist, wird eine neue Version des Zertifikats erstellt.
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());

Abrufen eines Zertifikats

Rufen Sie ein zuvor gespeichertes Zertifikat ab, indem Sie oder getCertificateVersionaufrufengetCertificate.

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

Aktualisieren eines vorhandenen Zertifikats

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

Löschen eines Zertifikats

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

Auflisten von Zertifikaten

Listen Sie die Zertifikate im Schlüsseltresor auf, indem Sie aufrufen 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());
}

Asynchrone API

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

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

asynchrones Erstellen eines Zertifikats

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

  • beginCreateCertificateerstellt ein neues Zertifikat im Azure-Key Vault. Wenn bereits ein Zertifikat mit demselben Namen vorhanden ist, wird eine neue Version des Zertifikats erstellt.
// 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());
    });

asynchrones Abrufen eines Zertifikats

Rufen Sie ein zuvor gespeichertes Zertifikat ab, indem Sie oder getCertificateVersionaufrufengetCertificate.

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

Aktualisieren eines vorhandenen Zertifikats asynchron

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

asynchrones Löschen eines Zertifikats

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

asynchrones Auflisten von Zertifikaten

Listen Sie die Zertifikate im Azure-Key Vault auf, indem Sie aufrufenlistPropertiesOfCertificates.

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

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung .

Allgemein

Azure Key Vault Certificate Clients lösen Ausnahmen aus. Wenn Sie beispielsweise versuchen, ein Zertifikat 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 {
    certificateClient.getCertificate("<deleted-certificate-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,die native Bibliotheken für Linux/macOS/Windows enthält und eine bessere Leistung im Vergleich zur Standard-SSL-Implementierung innerhalb des JDK bietet. 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 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