Java 用 Azure Identity クライアントライブラリ - バージョン 1.10.4

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

Azure Id ライブラリは、Azure SDK 全体で Azure Active Directory (Azure AD) トークン認証のサポートを提供します。これは、Azure AD トークン認証をサポートする Azure SDK クライアントを構築するために使用できる TokenCredential 実装のセットを提供します。

ソースコード | API リファレンスドキュメント | Azure AD のドキュメント

作業の開始

パッケージを組み込む

BOM ファイルを含める

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

<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 直接依存関係を含めます。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

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

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.1</version>
</dependency>

前提条件

Java Development Kit (JDK) バージョン 8 以降。
Azure サブスクリプション。
Azure CLI は、開発環境での認証、アカウントの作成、アカウントロールの管理にも役立ちます。

クライアントを認証する

コードをローカルでデバッグして実行する場合、開発者は独自のアカウントを使用して Azure サービスへの呼び出しを認証するのが一般的です。開発環境でこの認証を実行するために使用できる開発者ツールがいくつかあります。

Azure Toolkit for IntelliJ
Visual Studio Code Azure アカウント拡張機能
- これは、0.9.11 より新しい Azure アカウント拡張機能バージョンでは機能しない既知の問題VisualStudioCodeCredentialです。この問題に対する長期的な修正が進行中です。それまでの間は、Azure CLI (以下) を使用した認証を検討してください。
Azure CLI

上記の各項目を選択して、Azure ID 認証用に構成する方法について説明します。

主要な概念

資格証明

資格情報はクラスの一種であり、サービスクライアントが要求を認証するために必要なデータを格納、または取得できます。 Azure SDK 全体のサービスクライアントは、作成時に資格情報を受け入れます。サービスクライアントは、これらの資格情報を使用してサービスに対する要求を認証します。

Azure Identity ライブラリは、Azure AD での OAuth 認証に焦点を当てており、サービス要求を認証するための Azure AD トークンを取得できるさまざまな資格情報クラスを提供しています。このライブラリ内のすべての資格情報クラスは、azure-core の抽象クラスのTokenCredential実装であり、を使用して認証TokenCredentialできるサービスクライアントを構築するために、で使用できます。

使用可能な資格情報クラスの完全な一覧については、「資格情報クラス」を参照してください。

DefaultAzureCredential

DefaultAzureCredentialは、アプリケーションが最終的に Azure で実行されることを意図しているほとんどのシナリオに適しています。これは、一般的にデプロイ時の認証に使用される資格情報と、開発環境での認証に使用される資格情報が組み合わせて DefaultAzureCredential に使用されているためです。

注: DefaultAzureCredential は、適切な既定の動作で一般的なシナリオを処理することで、SDK の使用を簡単にすることを目的としています。開発者がもっと多くの制御が必要な場合や、シナリオが既定の設定で提供されない場合は、他の資格情報の種類を使用する必要があります。

DefaultAzureCredential は、次のメカニズムを順に経由して認証を試行します。

DefaultAzureCredential の認証フロー

[環境] - 環境変数DefaultAzureCredentialで指定されたアカウント情報が読み取られ、認証に使用されます。
ワークロード ID - ワークロード ID webhook によって設定された環境変数を使用してアプリが Kubernetes にデプロイされている場合、 DefaultAzureCredential 構成された ID が認証されます。
マネージド ID - マネージド ID が 有効になっている Azure ホストにアプリケーションがデプロイされている場合、 DefaultAzureCredential はそのアカウントで認証されます。
Azure Developer CLI - 開発者が Azure Developer CLI azd auth login コマンドを使用してアカウントを認証した場合、 DefaultAzureCredential はそのアカウントで認証されます。
IntelliJ - 開発者が Azure Toolkit for IntelliJ を使用して認証した場合、 DefaultAzureCredential はそのアカウントで認証されます。
Azure CLI - 開発者が Azure CLI az login コマンドを使用してアカウントを認証した場合、 DefaultAzureCredential はそのアカウントで認証されます。
Azure PowerShell - 開発者が Azure PowerShell Connect-AzAccount コマンドを使用してアカウントを認証した場合、 DefaultAzureCredential はそのアカウントで認証されます。

継続ポリシー

v1.10.0 以降では、 DefaultAzureCredential 以前の開発者資格情報が発生したエラーに関係なく、成功するまで、すべての開発者資格情報で認証が試行されます。たとえば、開発者の資格情報がトークンの取得を試み、失敗する可能性があるため DefaultAzureCredential 、フロー内の次の資格情報に進みます。デプロイされたサービス資格情報は、トークンの取得を試みることができるが、受け取らない場合、スローされた例外でフローを停止します。

これにより、デプロイされた動作を予測可能にしながら、コンピューター上のすべての開発者資格情報を試すことができます。

に関する注意 `VisualStudioCodeCredential`

既知の問題により、 VisualStudioCodeCredential がトークンチェーンからDefaultAzureCredential削除されました。今後のリリースで問題が解決されると、この変更は元に戻されます。

例

さまざまな資格情報の使用例については、「 Azure Identity Examples Wiki」ページを参照してください。

で認証する `DefaultAzureCredential`

この例では、DefaultAzureCredential を使用して azure-security-keyvault-secrets クライアントライブラリから SecretClient を認証することを示しています。

/**
 * The default credential first checks environment variables for configuration.
 * If environment configuration is incomplete, it will try managed identity.
 */
public void createDefaultAzureCredential() {
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(defaultCredential)
        .buildClient();
}

ワークステーションまたは Azure でを DefaultAzureCredential 構成する方法の詳細については、「DefaultAzureCredential の構成」を参照してください。

を使用してユーザー割り当てマネージド ID を認証する `DefaultAzureCredential`

ユーザー割り当てマネージド ID を使用して認証するには、ここでサポートされている Azure リソースの構成手順が正常に完了していることを確認します。

次の例では、ユーザー割り当てマネージド ID が構成された Azure リソースにデプロイされたを使用してDefaultAzureCredential、azure-security-keyvault-secrets クライアントライブラリからを認証SecretClientする方法を示します。

Azure リソースのユーザー割り当てマネージド ID を構成する方法の詳細については、「Azure リソースのマネージド ID を有効にする」を参照してください。

/**
 * The default credential will use the user assigned managed identity with the specified client ID.
 */
public void createDefaultAzureCredentialForUserAssignedManagedIdentity() {
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
        .managedIdentityClientId("<MANAGED_IDENTITY_CLIENT_ID>")
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(defaultCredential)
        .buildClient();
}

コードを使用してを managedIdentityClientId 構成するだけでなく、環境変数を AZURE_CLIENT_ID 使用して設定することもできます。これら 2 つの方法は、を使用する場合と同等です DefaultAzureCredential。

Azure Toolkit for IntelliJ でユーザーを認証する `DefaultAzureCredential`

IntelliJ を使用して認証するには、ここでの構成手順が正常に完了していることを確認します。

次の例では、IntelliJ IDEA がSecretClientインストールされているワークステーションで、を使用して DefaultAzureCredentialazure-security-keyvault-secrets クライアントライブラリからを認証し、ユーザーが Azure アカウントで Azure Toolkit for IntelliJ にサインインしたことを示します。

「Azure Toolkit for IntelliJ for IntelliJCredential にサインインする」で IntelliJ IDEA を構成する方法の詳細を参照してください。

/**
 * The default credential will use the KeePass database path to find the user account in IntelliJ on Windows.
 */
public void createDefaultAzureCredentialForIntelliJ() {
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
        // KeePass configuration required only for Windows. No configuration needed for Linux / Mac
        .intelliJKeePassDatabasePath("C:\\Users\\user\\AppData\\Roaming\\JetBrains\\IdeaIC2020.1\\c.kdbx")
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(defaultCredential)
        .buildClient();
}

マネージド ID のサポート

マネージド ID 認証は、次の Azure サービスのまたはをManagedIdentityCredential介してDefaultAzureCredential直接サポートされます。

メモ：マネージド ID 認証にトークンキャッシュのサポートを利用するには、バージョン1.7.0以降を使用azure-identityします。

例

マネージド ID を使用して Azure で認証する

この例では、システム割り当てマネージド ID またはユーザー割り当てマネージド ID が有効になっている Azure 上の仮想マシン、App Service、関数アプリ、クラウドシェル、または AKS 環境でを使用してManagedIdentityCredential、azure-security-keyvault-secrets クライアントライブラリからを認証SecretClientする方法を示します。

マネージド ID 用に Azure リソースを構成する方法の詳細については、「Azure リソースのマネージド ID を有効にする」を参照してください

/**
 * Authenticate with a User Assigned Managed identity.
 */
public void createManagedIdentityCredential() {
    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
        .clientId("<USER ASSIGNED MANAGED IDENTITY CLIENT ID>") // only required for user assigned
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(managedIdentityCredential)
        .buildClient();
}

/**
 * Authenticate with a System Assigned Managed identity.
 */
public void createManagedIdentityCredential() {
    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(managedIdentityCredential)
        .buildClient();
}

`ChainedTokenCredential` を使用してカスタム認証フローを定義する

一般に DefaultAzureCredential は Azure 用アプリケーションの開発を開始する最も簡単な方法ですが、より上級のユーザーは、認証時に考慮される資格情報をカスタマイズできます。 ChainedTokenCredential を使用すると、ユーザーは複数の資格情報インスタンスを組み合わせて、カスタマイズされた資格情報チェーンを定義できます。この例では、を作成する方法を ChainedTokenCredential示します。

マネージド ID を使用して認証を試みます。
現在の環境でマネージド ID が使用できない場合は、Azure CLI を使用した認証にフォールバックします。

// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.

    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder().build();
    AzureCliCredential cliCredential = new AzureCliCredentialBuilder().build();

    ChainedTokenCredential credential = new ChainedTokenCredentialBuilder().addLast(managedIdentityCredential).addLast(cliCredential).build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(credential)
        .buildClient();

クラウドの構成

資格情報は、Azure パブリッククラウドの Azure AD エンドポイントに対する認証に既定で設定されます。 Azure Governmentやプライベートクラウドなどの他のクラウドのリソースにアクセスするには、引数を使用して資格情報をauhtorityHost構成します。 AzureAuthorityHosts は、既知のクラウドの機関を定義します。

DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder()
    .authorityHost(AzureAuthorityHosts.AZURE_GOVERNMENT)
    .build();

すべての資格情報でこの構成が必要なわけではありません。などの AzureCliCredential開発ツールを使用して認証する資格情報は、そのツールの構成を使用します。同様に、は引数をauthority受け入れますが、VisualStudioCodeCredential既定では VS Code の "Azure: Cloud" 設定に一致する機関になります。

資格情報クラス

Azure でホストされるアプリケーションを認証する

Azure でホストされるアプリケーションを認証する
Credential クラス	使用法	例
`DefaultAzureCredential`	は、Azure で実行されるアプリケーションの開発を迅速に開始するための簡素化された認証エクスペリエンスを提供します	例
`ChainedTokenCredential`	を使用すると、ユーザーは複数の資格情報を構成するカスタム認証フローを定義できます	例
`EnvironmentCredential`	環境変数で指定された資格情報を使用してサービスプリンシパルまたはユーザーを認証する
`ManagedIdentityCredential`	Azure リソースのマネージド ID を認証します	例
`WorkloadIdentityCredential`	Kubernetes で Azure AD ワークロード ID をサポート	例

サービスプリンシパルを認証する

サービスプリンシパルを認証する
Credential クラス	使用法	例	リファレンス
`ClientAssertionCredential`	署名されたクライアントアサーションを使用してサービスプリンシパルを認証します
`ClientCertificateCredential`	証明書を使用してサービスプリンシパルを認証する	例	サービスプリンシパルの認証
`ClientSecretCredential`	シークレットを使用してサービスプリンシパルを認証する	例	サービスプリンシパルの認証

ユーザーを認証する

ユーザーを認証する
Credential クラス	使用法	例	リファレンス
`AuthorizationCodeCredential`	Oauth 2 フローの一部として、以前に取得した承認コードを使用してユーザーを認証する		OAuth2 認証コード
`DeviceCodeCredential`	限られた UI を使用してデバイスでユーザーを対話形式で認証する	例	デバイスコード認証
`InteractiveBrowserCredential`	既定のシステムブラウザーを使用してユーザーを対話形式で認証する	例	OAuth2 認証コード
`OnBehalfOfCredential`	は、委任されたユーザー ID とアクセス許可を要求チェーンを介して伝達します		代理認証
`UsernamePasswordCredential`	多要素認証なしでユーザー名とパスワードを使用してユーザーを認証する	例	ユーザー名とパスワードによる認証

開発ツールを使用した認証

開発ツールを使用した認証
Credential クラス	使用法	例	リファレンス
`AzureCliCredential`	Azure CLI で有効なユーザーまたはサービスプリンシパルを使用して開発環境で認証する	例	Azure CLI 認証
`AzureDeveloperCliCredential`	Azure Developer CLIで有効なユーザーまたはサービスプリンシパルを使用して開発環境で認証する		Azure Developer CLI リファレンス
`AzurePowerShellCredential`	Azure PowerShellで有効なユーザーまたはサービスプリンシパルを使用して開発環境で認証する	例	Azure PowerShell ドキュメント
`IntelliJCredential`	Azure Toolkit for IntelliJ のアカウントを使用して開発環境で認証する	例	IntelliJ 認証
`VisualStudioCodeCredential`	Visual Studio Code Azure アカウント拡張機能のアカウントを使用して、開発環境で認証を行います。	例	VS Code Azure Account の拡張機能

メモ： Azure Identity ライブラリ内のすべての資格情報の実装はスレッドセーフであり、1 つの資格情報インスタンスを使用して複数のサービスクライアントを作成できます。

資格情報は、を使用 ChainedTokenCredentialして成功するまで順番に試行されるように連結できます。詳細については、「資格情報のチェーン」を参照してください。

環境変数

DefaultAzureCredential と EnvironmentCredential は環境変数を使用して構成できます。認証の種類ごとに、特定の変数の値が必要です。

シークレットを持つサービスプリンシパル

シークレットを持つサービスプリンシパル
変数名	値
`AZURE_CLIENT_ID`	Azure AD アプリケーションの ID
`AZURE_TENANT_ID`	アプリケーションの Azure AD テナントの ID
`AZURE_CLIENT_SECRET`	アプリケーションのクライアントシークレットの 1 つ

証明書を使用したサービスプリンシパル

証明書を使用したサービスプリンシパル
変数名	値
`AZURE_CLIENT_ID`	Azure AD アプリケーションの ID
`AZURE_TENANT_ID`	アプリケーションの Azure AD テナントの ID
`AZURE_CLIENT_CERTIFICATE_PATH`	秘密キーを含む PFX または PEM でエンコードされた証明書ファイルへのパス
`AZURE_CLIENT_CERTIFICATE_PASSWORD`	(省略可能) 証明書のパスワード。この値が指定されていない限り、証明書をパスワードで保護することはできません。

ユーザー名とパスワード

ユーザー名とパスワード
変数名	値
`AZURE_CLIENT_ID`	Azure AD アプリケーションの ID
`AZURE_TENANT_ID`	(省略可能)アプリケーションの Azure AD テナントの ID
`AZURE_USERNAME`	ユーザー名 (通常はメールアドレス)
`AZURE_PASSWORD`	そのユーザーのパスワード

構成は上記の順序で試行されます。たとえば、クライアントシークレットと証明書の値が両方存在する場合、クライアントシークレットが使用されます。

継続的アクセス評価

v1.10.0 の時点では、継続的アクセス評価 (CAE) によって保護されたリソースへのアクセスは、要求ごとに可能です。これは API を使用してTokenRequestContext.setCaeEnabled(boolean)有効にすることができます。 CAE は、開発者の資格情報ではサポートされていません。

トークンのキャッシュ

トークンキャッシュは、アプリが次の操作を可能にする Azure Identity ライブラリによって提供される機能です。

メモリ内またはディスク (オプトイン) にトークンをキャッシュします。
回復性とパフォーマンスを向上させます。
アクセストークンを取得するために Azure AD に対して行われる要求の数を減らします。

Azure Identity ライブラリには、メモリ内と永続的なディスクキャッシュの両方が用意されています。詳細については、トークンキャッシュに関するドキュメントを参照してください。

トラブルシューティング

資格情報は、認証に失敗したとき、または認証を実行できない場合に例外を発生させます。資格情報の認証に失敗すると、ClientAuthenticationException が発生します。例外には属性があり message 、認証が失敗した理由を説明します。によってこの例外が発生 ChainedTokenCredentialすると、基になる資格情報リストのチェーン実行が停止されます。

資格情報がコンピューターで使用できない状態で必要な基になるリソースのいずれかが原因で資格情報で認証を実行できない場合、CredentialUnavailableException が発生します。例外には、資格情報が message 認証の実行に使用できない理由を説明する属性があります。によってこの例外が発生 ChainedTokenCredentialすると、メッセージはチェーン内の各資格情報からエラーメッセージを収集します。

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

次の手順

ここに記載されている Java クライアントライブラリでは、と Azure Identity ライブラリを使用TokenCredentialした認証がサポートされています。その使用方法の詳細については、こちらのリンクを参照してください。サンプルと共に、これらのクライアントライブラリの使用に関するその他のドキュメントを参照してください。

microsoft-graph-sdk では、と Azure Identity ライブラリを使用TokenCredentialした認証もサポートされています。

共同作成

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

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

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

インプレッション数

次の方法で共有

Java 用 Azure Identity クライアントライブラリ - バージョン 1.10.4

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

主要な概念

資格証明

DefaultAzureCredential

継続ポリシー

に関する注意 `VisualStudioCodeCredential`

例

で認証する `DefaultAzureCredential`

を使用してユーザー割り当てマネージド ID を認証する `DefaultAzureCredential`

Azure Toolkit for IntelliJ でユーザーを認証する `DefaultAzureCredential`

マネージド ID のサポート

例

マネージド ID を使用して Azure で認証する

`ChainedTokenCredential` を使用してカスタム認証フローを定義する

クラウドの構成

資格情報クラス

Azure でホストされるアプリケーションを認証する

サービスプリンシパルを認証する

ユーザーを認証する

開発ツールを使用した認証

環境変数

シークレットを持つサービスプリンシパル

証明書を使用したサービスプリンシパル

ユーザー名とパスワード

継続的アクセス評価

トークンのキャッシュ

トラブルシューティング

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

Java 用 Azure Identity クライアント ライブラリ - バージョン 1.10.4

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

主要な概念

資格証明

DefaultAzureCredential

継続ポリシー

に関する注意 VisualStudioCodeCredential

例

で認証する DefaultAzureCredential

を使用してユーザー割り当てマネージド ID を認証する DefaultAzureCredential

Azure Toolkit for IntelliJ でユーザーを認証する DefaultAzureCredential

マネージド ID のサポート

例

マネージド ID を使用して Azure で認証する

ChainedTokenCredential を使用してカスタム認証フローを定義する

クラウドの構成

資格情報クラス

Azure でホストされるアプリケーションを認証する

サービス プリンシパルを認証する

ユーザーを認証する

開発ツールを使用した認証

環境変数

シークレットを持つサービス プリンシパル

証明書を使用したサービス プリンシパル

ユーザー名とパスワード

継続的アクセス評価

トークンのキャッシュ

トラブルシューティング

次の手順

共同作成

フィードバック

その他のリソース

Java 用 Azure Identity クライアントライブラリ - バージョン 1.10.4

に関する注意 `VisualStudioCodeCredential`

で認証する `DefaultAzureCredential`

を使用してユーザー割り当てマネージド ID を認証する `DefaultAzureCredential`

Azure Toolkit for IntelliJ でユーザーを認証する `DefaultAzureCredential`

`ChainedTokenCredential` を使用してカスタム認証フローを定義する

サービスプリンシパルを認証する

シークレットを持つサービスプリンシパル

証明書を使用したサービスプリンシパル