次の方法で共有


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

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>

前提条件

クライアントを認証する

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

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

主要な概念

資格証明

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

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

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

DefaultAzureCredential

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

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

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

DefaultAzureCredential の認証フロー

  1. [環境] - 環境変数DefaultAzureCredentialで指定されたアカウント情報が読み取られ、認証に使用されます。
  2. ワークロード ID - ワークロード ID webhook によって設定された環境変数を使用してアプリが Kubernetes にデプロイされている場合、 DefaultAzureCredential 構成された ID が認証されます。
  3. マネージド ID - マネージド ID が 有効になっている Azure ホストにアプリケーションがデプロイされている場合、 DefaultAzureCredential はそのアカウントで認証されます。
  4. Azure Developer CLI - 開発者が Azure Developer CLI azd auth login コマンドを使用してアカウントを認証した場合、 DefaultAzureCredential はそのアカウントで認証されます。
  5. IntelliJ - 開発者が Azure Toolkit for IntelliJ を使用して認証した場合、 DefaultAzureCredential はそのアカウントで認証されます。
  6. Azure CLI - 開発者が Azure CLI az login コマンドを使用してアカウントを認証した場合、 DefaultAzureCredential はそのアカウントで認証されます。
  7. 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 リソースにデプロイされた を使用してDefaultAzureCredentialazure-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 環境で を使用してManagedIdentityCredentialazure-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して成功するまで順番に試行されるように連結できます。詳細については、「 資格情報のチェーン」 を参照してください。

環境変数

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

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

シークレットを持つサービス プリンシパル
変数名
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 宛てに質問またはコメントをお送りください。

インプレッション数