Go 用 Azure ID ライブラリ内の資格情報チェーン

Azure Identity ライブラリには 、資格情報 (Azure Core ライブラリの TokenCredential インターフェイスを実装するパブリック型) が用意されています。 資格情報は、Microsoft Entra ID からアクセス トークンを取得するための個別の認証フローを表します。 これらの資格情報を連結して、試行する順序付けられた一連の認証メカニズムを形成できます。

資格情報チェーンのしくみ

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

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

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

• 環境認識: アプリが実行されている環境に基づいて、最も適切な資格情報を自動的に選択します。 これを使用しない場合は、次のようなコードを記述する必要があります。

  // Set up credential based on environment (Azure or local development)
  if os.Getenv("WEBSITE_HOSTNAME") != "" {
      clientID := azidentity.ClientID("abcd1234-...")
      opts := azidentity.ManagedIdentityCredentialOptions{ID: clientID}
      credential, err = azidentity.NewManagedIdentityCredential(&opts)
  
      if err != nil {
        // TODO: handle error
      }
  } else {
      // Use Azure CLI Credential
      credential, err = azidentity.NewAzureCLICredential(nil)
  
      if err != nil {
        // TODO: handle error
      }
  }
  

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

• 堅牢性の向上: 前の資格情報がアクセス トークンの取得に失敗した場合、次の資格情報に移行するバックアップ機構が備わっています。

連結された認証情報を選択する方法

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

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

DefaultAzureCredential の概要

DefaultAzureCredential は、特定の設定が施された、構成済みの資格情報チェーンです。 これは、最も一般的な認証フローと開発者ツールと共に、多くの環境をサポートするように設計されています。 グラフィカルな形式では、基になるチェーンは次のようになります。

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

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

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
    )

// create a credential
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    // TODO: handle error
}

// create a Blob service client 
accountURL := "https://<my_account_name>.blob.core.windows.net"
client, err := azblob.NewClient(accountURL, credential, nil)
if err != nil {
    // TODO: handle error
}

DefaultAzureCredential をカスタマイズする方法

すべての Developer tool または Deployed service 資格情報を除外するには、環境変数の AZURE_TOKEN_CREDENTIALS をそれぞれ prod または devに設定します。 prodの値を使用すると、基になる資格情報チェーンは次のようになります。

devの値を使用すると、チェーンは次のようになります。

ChainedTokenCredential の概要

ChainedTokenCredential は、アプリのニーズに合わせて資格情報を追加する空のチェーンです。 例えば：

azCLI, err := azidentity.NewAzureCLICredential(nil)
if err != nil {
  // handle error
}

azdCLI, err := azidentity.NewAzureDeveloperCLICredential(nil)
if err != nil {
  // handle error
}

chain, err := azidentity.NewChainedTokenCredential([]azcore.TokenCredential{azCLI, azdCLI}, nil)
if err != nil {
  // handle error
}

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

DefaultAzureCredential の使用ガイダンス

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

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

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

チェーンされた資格情報をデバッグする

予期しない問題を診断したり、チェーンに含まれる資格情報の動作を理解するには、アプリでログ記録を有効化します。 必要に応じて、Azure Identity クライアント ライブラリから出力されたイベントのみにログをフィルター処理します。 例えば：

import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
// print log output to stdout
azlog.SetListener(func(event azlog.Event, s string) {
    fmt.Println(s)
})
// include only azidentity credential logs
azlog.SetEvents(azidentity.EventAuthentication)

特定の資格情報の種類からのエラーの解決に関するガイダンスについては、トラブルシューティング ガイドのを参照してください。