C++ 用 Azure ID クライアント ライブラリ内の資格情報チェーン

Azure Identity クライアント ライブラリは 、資格情報 (Azure Core ライブラリの TokenCredential 抽象基本クラスから派生したパブリック型) を提供します。 資格情報は、Microsoft Entra ID からアクセス トークンを取得するための個別の認証フローを表します。 これらの資格情報を連結することにより、試行される一連の認証メカニズムを順序付けたシーケンスを形成できます。

資格情報チェーンのしくみがどのように機能するか

資格情報チェーンでは、実行時に、シーケンスの最初の資格情報を使用した認証が試行されます。 その資格情報がアクセス トークンの取得に失敗した場合は、アクセス トークンが正常に取得されるまで、シーケンス内の次の資格情報が試行されます。 次のシーケンス図はこの動作を示しています。

資格情報チェーンを使用する理由

資格情報チェーンの使用には、次の利点があります。

• 環境認識: アプリが実行されている環境に基づいて、最も適切な資格情報が自動的に選択されます。 それがなければ、次のようなコードを書く必要があります。

  // Set up credential based on environment (Azure or local development)
  std::shared_ptr<Azure::Core::Credentials::TokenCredential> credential;
  if (!std::getenv("WEBSITE_HOSTNAME"))
  {
      credential = std::make_shared<Azure::Identity::AzureCliCredential>();
  }
  else
  {
      credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>();
  }
  

• シームレスな移行: 認証コードを変更することなく、アプリをローカル開発からステージング環境または運用環境に移行できます。

• 回復性の向上: 前の認証情報でアクセス トークンの取得に失敗すると次の認証情報に移る、フォールバック メカニズムが含まれています。

チェーンされた資格情報を選択する方法

C++ では、資格情報チェーンには次の 2 つの選択肢があります。

• 事前構成済みチェーンを使用する: DefaultAzureCredential 型によって実装された事前構成済みチェーンを使用します。 この方法については、「DefaultAzureCredential の概要」セクションを参照してください。
• カスタム資格情報チェーンを構築する: 空のチェーンから始めて、必要なものだけを含めます。 この方法については、「ChainedTokenCredential の概要」セクションを参照してください。

DefaultAzureCredential の概要

DefaultAzureCredential は、独自の基準に基づいて事前構成された資格情報のチェーンです。 これは、最も一般的な認証フローおよび開発者ツールのほか、多くの環境をサポートするように設計されています。 基になるチェーンをグラフィカルな形式で示すと、次のようになります。

DefaultAzureCredential が資格情報を試行する順序は次のとおりです。

DefaultAzureCredential は、最も単純な形式として次のようにパラメーターなしのバージョンを使用することもできます。

#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

ChainedTokenCredential の概要

ChainedTokenCredential は、アプリのニーズに合わせて資格情報を追加するための空のチェーンです。 例えば次が挙げられます。

#include <azure/identity/azure_cli_credential.hpp>
#include <azure/identity/chained_token_credential.hpp>
#include <azure/identity/managed_identity_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
        Azure::Identity::ChainedTokenCredential::Sources{
            std::make_shared<Azure::Identity::AzureCliCredential>(),
            std::make_shared<Azure::Identity::ManagedIdentityCredential>()});

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

前のコード サンプルでは、2 つの資格情報で構成されるカスタマイズされた資格情報チェーンを作成します。 AzureCliCredential が最初に試行され、必要に応じて ManagedIdentityCredentialが続きます。 このチェーンをグラフィカルな形式で示すと、次のようになります。

DefaultAzureCredential の使用ガイド

DefaultAzureCredential は間違いなく、Azure Identity クライアント ライブラリの使用を開始する最も簡単な方法ですが、その利便性によってトレードオフが生まれます。 アプリを Azure にデプロイしたら、アプリの認証要件を理解する必要があります。 そのため、DefaultAzureCredential を特定の TokenCredential 実装 (ManagedIdentityCredentialなど) に置き換えます。

その理由は次のとおりです。

• デバッグが困難: 認証が失敗した場合、問題となっている資格情報のデバッグや特定が困難になることがあります。 1 つの資格情報から次の資格情報への進行状況や、それぞれの成功/失敗の状態を確認するには、ログ記録を有効にする必要があります。 詳細については、「連結された資格情報のデバッグ」を参照してください。
• パフォーマンスのオーバーヘッド: 複数の資格情報を順番に試すプロセスにより、パフォーマンスのオーバーヘッドが発生する可能性があります。 たとえば、ローカル開発マシンでの実行時に、マネージド ID は使用できません。 そのため、ManagedIdentityCredential は常にローカル開発環境で失敗します。
• 予測不可能な動作: DefaultAzureCredential では、特定の環境変数の存在確認が行われます。 ホスト マシン上のシステム レベルでは、これらの環境変数の追加または変更が行われる可能性があります。 このような変更はグローバルに適用されるため、そのマシンで実行されているアプリで、DefaultAzureCredential のランタイム動作が変更されます。

チェーン化された資格情報のデバッグ

予期しない問題を診断したり、チェーンに含まれる資格情報の動作を理解するには、アプリでログ記録を有効化します。 たとえば、パラメーターなしの形式の DefaultAzureCredential を使用して Blob Storage アカウントへの要求を認証したとします。 アプリはローカル開発環境で実行され、開発者は Azure CLI を使用して Azure に認証されます。 アプリを実行すると、次の関連するエントリが出力に表示されます。

DEBUG : Identity: Creating DefaultAzureCredential which combines multiple parameterless credentials into a single one.
DefaultAzureCredential is only recommended for the early stages of development, and not for usage in production environment.
Once the developer focuses on the Credentials and Authentication aspects of their application, DefaultAzureCredential needs to be replaced with the credential that is the better fit for the application.
INFO  : Identity: EnvironmentCredential gets created with ClientSecretCredential.
DEBUG : Identity: EnvironmentCredential: 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET' environment variables are set, so ClientSecretCredential with corresponding tenantId, clientId, and clientSecret gets created.
WARN  : Identity: Azure Kubernetes environment is not set up for the WorkloadIdentityCredential credential to work.
INFO  : Identity: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2019 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2017 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Cloud Shell source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Azure Arc source.
INFO  : Identity: ManagedIdentityCredential will be created with Azure Instance Metadata Service source.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, AzureCliCredential, ManagedIdentityCredential.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from EnvironmentCredential: GetToken(): error response: 400 Bad Request

{"error":"invalid_grant","error_description":"AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance. Trace ID: 11223344-5566-7788-9900-aabbccddeeff Correlation ID: ffeeddcc-bbaa-9988-7766-554433221100 Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"11223344-5566-7788-9900-aabbccddeeff","correlation_id":"ffeeddcc-bbaa-9988-7766-554433221100","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"01234567-89ab-cdef-fedc-ba9876543210\"]}}}"}
WARN  : Identity: WorkloadIdentityCredential authentication unavailable. See earlier WorkloadIdentityCredential log messages for details.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from WorkloadIdentityCredential: WorkloadIdentityCredential authentication unavailable. Azure Kubernetes environment is not set up correctly.
INFO  : Identity: DefaultAzureCredential: Successfully got token from AzureCliCredential. This credential will be reused for subsequent calls.
DEBUG : Identity: DefaultAzureCredential: Saved this credential at index 2 for subsequent calls.

上の出力では、次のことがわかります。

• EnvironmentCredentialとWorkloadIdentityCredentialは、それぞれの順で Microsoft Entra アクセス トークンの取得に失敗しました。
• "AzureCliCredential" で始まるエントリで示されているように、Successfully got token from AzureCliCredentialは成功します。 AzureCliCredential が成功したため、それ以降の資格情報は試行されませんでした。