次の方法で共有


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

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>

前提条件

クライアントを認証する

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 宛てに質問またはコメントをお送りください。

インプレッション数