Java 用 Azure Key Vault 証明書クライアントライブラリ - バージョン 4.5.7

[アーティクル]
10/21/2023

Azure Key Vaultを使用すると、証明書を安全に管理し、厳密に制御できます。 Azure Key Vault 証明書クライアントライブラリでは、RSA キーと EC キーによってサポートされる証明書がサポートされています。

複数の証明書と同じ証明書の複数のバージョンをKey Vaultに保持できます。証明書をバックアップする Azure Key Vaultの暗号化キーは、JSON Web キー (JWK) オブジェクトとして表されます。このライブラリには、証明書とそのバージョンを作成、取得、更新、削除、消去、バックアップ、復元、および一覧表示する操作が用意されています。

ソースコード | API リファレンスドキュメント | 製品ドキュメント | サンプル

作業の開始

パッケージを組み込む

BOM ファイルを含める

ライブラリの azure-sdk-bom 一般提供 (GA) バージョンに依存するには、をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

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

次に、次に示すように、バージョンタグを使用せずに、依存関係セクションに直接依存関係を含めます。

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

直接依存関係を含める

BOM に存在しない特定のバージョンのライブラリに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

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

前提条件

Java Development Kit (JDK) バージョン 8 以降。
Azure サブスクリプション。
既存の Azure Key Vault。キーコンテナーを作成する必要がある場合は、このドキュメントの手順に従って Azure Portal で作成できます。または、このドキュメントの手順に従って Azure CLI を使用することもできます。

クライアントを認証する

Azure Key Vault サービスと対話するには、クラスのインスタンス、コンテナー URLCertificateClient、資格情報オブジェクトを作成する必要があります。このドキュメントに示す例では、という名前 DefaultAzureCredentialの資格情報オブジェクトを使用します。これは、ローカルの開発環境や運用環境を含むほとんどのシナリオに適しています。さらに、運用環境での認証には [マネージド ID][managed_identity] を使用することをお勧めします。

さまざまな認証方法とそれに対応する資格情報の種類の詳細については、 Azure ID のドキュメントを参照してください。

証明書クライアントを作成する

最適な認証設定を実行し、your-key-vault-url をキーコンテナーの URL に置き換えたら、をCertificateClient作成できます。

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

注: 非同期クライアントを使用する場合は、ではなくを使用CertificateAsyncClientCertificateClientし、を呼び出しますbuildAsyncClient()。

主要な概念

Certificate

Azure Key Vault では、シークレットコンテンツタイプ (PKCS12&PEM) を持つ証明書がサポートされています。証明書は、種類 (EC&RSA) の Azure Key Vaultのキーによってサポートできます。証明書ポリシーに加えて、次の属性を指定できます。

enabled: 証明書が有効で使用可能かどうかを指定します。
created: このバージョンの証明書がいつ作成されたかを示します。
updated: このバージョンの証明書が更新された日時を示します。

証明書クライアント

証明書クライアントは、証明書とそのバージョンを取得、設定、更新、削除、および一覧表示するために、Azure Key Vault サービスとの対話を実行します。クライアントでは、キーコンテナー内の証明書発行者と連絡先に対する CRUD 操作もサポートされています。非同期 (CertificateAsyncClient) クライアントと同期 (CertificateClient) クライアントが SDK に存在し、アプリケーションのユースケースに基づいてクライアントを選択できます。証明書を初期化したら、Azure Key Vaultでプライマリリソースの種類を操作できます。

例

同期 API

次のセクションでは、次のような最も一般的な Azure Key Vault証明書サービスタスクをカバーするいくつかのコードスニペットを示します。

証明書を作成します
証明書の取得
既存の証明書を更新する
証明書を削除します
証明書の一覧の取得

証明書を作成する

Azure Key Vaultに格納する証明書を作成します。

beginCreateCertificateは、Azure Key Vaultに新しい証明書を作成します。同じ名前の証明書が既に存在する場合は、証明書の新しいバージョンが作成されます。

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

証明書の取得

または getCertificateVersionを呼び出getCertificateして、以前に格納された証明書を取得します。

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

既存の証明書を更新する

を呼び出 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());

証明書の削除

を呼び出 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();

証明書の一覧の取得

を呼び出 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

次のセクションでは、次のような最も一般的な非同期 Azure Key Vault証明書サービスタスクをカバーするいくつかのコードスニペットを示します。

証明書を非同期的に作成する
証明書を非同期的に取得する
既存の証明書を非同期的に更新する
証明書を非同期的に削除する
証明書を非同期的に一覧表示する

注: メインアプリケーション/スレッドが終了する前に非同期関数/操作を実行して終了できるように、メインクラス/スレッドで関数呼び出しの後にまたは Thread.sleep() を追加System.in.read()する必要があります。

証明書を非同期的に作成する

Azure Key Vaultに格納する証明書を作成します。

beginCreateCertificateは、Azure Key Vaultに新しい証明書を作成します。同じ名前の証明書が既に存在する場合は、証明書の新しいバージョンが作成されます。

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

証明書を非同期的に取得する

または getCertificateVersionを呼び出getCertificateして、以前に格納された証明書を取得します。

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

既存の証明書を非同期的に更新する

を呼び出 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()));

証明書を非同期的に削除する

を呼び出 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());
    });

証明書を非同期的に一覧表示する

を呼び出listPropertiesOfCertificatesして、Azure Key Vault内の証明書を一覧表示します。

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

トラブルシューティング

さまざまな障害シナリオを診断する方法の詳細については、トラブルシューティングガイドを参照してください。

全般

Azure Key Vault 証明書クライアントでは例外が発生します。たとえば、削除 404 後に証明書を取得しようとすると、リソースが見つからなかったというエラーが返されます。次のスニペットでは、例外をキャッチし、エラーに関する追加情報を表示することで、エラーが適切に処理されます。

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

既定の HTTP クライアント

すべてのクライアントライブラリでは、Netty HTTP クライアントが既定で使用されます。前述の依存関係を追加すると、Netty HTTP クライアントを使用するようにクライアントライブラリが自動的に構成されます。 HTTP クライアントの構成と変更については、HTTP クライアントの Wiki で詳しく説明されています。

既定の SSL ライブラリ

すべてのクライアントライブラリは、Tomcat ネイティブの Boring SSL ライブラリを既定で使用して、SSL 操作にネイティブレベルのパフォーマンスを実現しています。 Boring SSL ライブラリは、Linux/macOS/Windows 用のネイティブライブラリを含む Uber JAR であり、JDK 内の既定の SSL 実装と比較してパフォーマンスが向上します。依存関係のサイズを縮小する方法など、詳細については、Wiki の「パフォーマンスチューニング」セクションを参照してください。

次の手順

SDK の GitHub リポジトリには、いくつかのKey Vault Java SDK サンプルが用意されています。これらのサンプルでは、Key Vaultの操作中に一般的に発生するその他のシナリオのコード例を示します。

次の手順のサンプル

サンプルについては、こちらを参照してください。

その他のドキュメント

Azure Key Vaultに関するより広範なドキュメントについては、API リファレンスドキュメントを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

次の方法で共有

Java 用 Azure Key Vault 証明書クライアントライブラリ - バージョン 4.5.7

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

証明書クライアントを作成する

主要な概念

Certificate

証明書クライアント

例

同期 API

証明書を作成する

証明書の取得

既存の証明書を更新する

証明書の削除

証明書の一覧の取得

非同期 API

証明書を非同期的に作成する

証明書を非同期的に取得する

既存の証明書を非同期的に更新する

証明書を非同期的に削除する

証明書を非同期的に一覧表示する

トラブルシューティング

全般

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

次の手順のサンプル

その他のドキュメント

共同作成

フィードバック

その他のリソース

次の方法で共有

Java 用 Azure Key Vault 証明書クライアント ライブラリ - バージョン 4.5.7

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

証明書クライアントを作成する

主要な概念

Certificate

証明書クライアント

例

同期 API

証明書を作成する

証明書の取得

既存の証明書を更新する

証明書の削除

証明書の一覧の取得

非同期 API

証明書を非同期的に作成する

証明書を非同期的に取得する

既存の証明書を非同期的に更新する

証明書を非同期的に削除する

証明書を非同期的に一覧表示する

トラブルシューティング

全般

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

次の手順のサンプル

その他のドキュメント

共同作成

フィードバック

その他のリソース

Java 用 Azure Key Vault 証明書クライアントライブラリ - バージョン 4.5.7