Java 用 Azure Key Vault シークレットクライアントライブラリ - バージョン 4.7.1

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

Azure Key Vault は、パスワードやデータベース接続文字列などのシークレットのセキュリティで保護されたストレージを提供するクラウドサービスです。

Azure Key Vault Secrets クライアントライブラリを使用すると、トークン、パスワード、API キー、その他のシークレットへのアクセスを安全に格納し、厳密に制御できます。このライブラリには、シークレットとそのバージョンを作成、取得、更新、削除、消去、バックアップ、復元、および一覧表示する操作が用意されています。

Azure Key Vault Secrets クライアントライブラリを使用して、シークレットを作成および管理します。

ソースコード | 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-secrets</artifactId>
    </dependency>
</dependencies>

直接依存関係を含める

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

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

前提条件

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

クライアントを認証する

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

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

シークレットクライアントを作成する

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

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

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

主要な概念

Secret

シークレットは、Azure Key Vault内の基本的なリソースです。開発者から見ると、Key Vault API はシークレット値を文字列として受け取って返します。シークレットデータに加えて、次の属性を指定できます。

enabled: シークレットデータを取得できるかどうかを指定します。
notBefore: シークレットがアクティブになる時間を識別します。
expires: シークレットデータを取得すべきでない有効期限を識別します。
created: このバージョンのシークレットがいつ作成されたかを示します。
updated: このバージョンのシークレットがいつ更新されたかを示します。

シークレットクライアント:

シークレットクライアントは、シークレットとそのバージョンを取得、設定、更新、削除、および一覧表示するために、Azure Key Vault サービスとの対話を実行します。 SDK には非同期 (SecretAsyncClient) クライアントと同期 (SecretClient) クライアントが存在し、アプリケーションのユースケースに基づいてクライアントを選択できます。シークレットを初期化したら、Key Vaultでプライマリリソースの種類を操作できます。

例

同期 API

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

シークレットを作成します
シークレットを取得する
既存のシークレットを更新する
シークレットを削除します
シークレットを一覧表示する

シークレットの作成

Azure Key Vaultに格納するシークレットを作成します。

setSecretは、Azure Key Vaultに新しいシークレットを作成します。指定した名前のシークレットが既に存在する場合は、新しいバージョンのシークレットが作成されます。

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

シークレットを取得する

を呼び出 getSecretして、以前に格納されたシークレットを取得します。

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

既存のシークレットを更新する

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

シークレットを削除します

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

シークレットのリスト

を呼び出listPropertiesOfSecretsして、Azure Key Vault内のシークレットを一覧表示します。

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

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

シークレットを非同期的に作成する
シークレットを非同期的に取得する
既存のシークレットを非同期的に更新する
シークレットを非同期的に削除する
シークレットを非同期的に一覧表示する

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

シークレットを非同期的に作成する

Azure Key Vaultに格納するシークレットを作成します。

setSecretは、Azure Key Vaultに新しいシークレットを作成します。指定した名前のシークレットが既に存在する場合は、新しいバージョンのシークレットが作成されます。

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

シークレットを非同期的に取得する

を呼び出 getSecretして、以前に格納されたシークレットを取得します。

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

既存のシークレットを非同期的に更新する

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

シークレットを非同期的に削除する

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

シークレットを非同期的に一覧表示する

を呼び出listPropertiesOfSecretsして、Azure Key Vault内のシークレットを一覧表示します。

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

トラブルシューティング

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

全般

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

try {
    secretClient.getSecret("<deleted-secret-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 の「パフォーマンスチューニング」セクションを参照してください。

次の手順

いくつかのKey Vault Java SDK サンプルは、SDK の GitHub リポジトリで入手できます。これらのサンプルでは、Azure 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.7.1

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

シークレットクライアントを作成する

主要な概念

Secret

シークレットクライアント:

例

同期 API

シークレットの作成

シークレットを取得する

既存のシークレットを更新する

シークレットを削除します

シークレットのリスト

非同期 API

シークレットを非同期的に作成する

シークレットを非同期的に取得する

既存のシークレットを非同期的に更新する

シークレットを非同期的に削除する

シークレットを非同期的に一覧表示する

トラブルシューティング

全般

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

次の手順のサンプル

その他のドキュメント

共同作成

フィードバック

その他のリソース

次の方法で共有

Java 用 Azure Key Vault シークレット クライアント ライブラリ - バージョン 4.7.1

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

シークレット クライアントを作成する

主要な概念

Secret

シークレット クライアント:

例

同期 API

シークレットの作成

シークレットを取得する

既存のシークレットを更新する

シークレットを削除します

シークレットのリスト

非同期 API

シークレットを非同期的に作成する

シークレットを非同期的に取得する

既存のシークレットを非同期的に更新する

シークレットを非同期的に削除する

シークレットを非同期的に一覧表示する

トラブルシューティング

全般

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

次の手順のサンプル

その他のドキュメント

共同作成

フィードバック

その他のリソース

Java 用 Azure Key Vault シークレットクライアントライブラリ - バージョン 4.7.1

シークレットクライアントを作成する

シークレットクライアント: