Python 用 Azure Identity クライアント ライブラリ - バージョン 1.14.1
Azure Id ライブラリは、Azure SDK 全体で Azure Active Directory (Azure AD) トークン認証のサポートを提供します。 一連の TokenCredential 実装が用意されており、これを使用して、Azure AD トークン認証をサポートする Azure SDK クライアントを構築できます。
ソースコード | パッケージ (PyPI) | パッケージ (Conda) | API リファレンス ドキュメント | Azure AD のドキュメント
作業の開始
パッケージをインストールする
pip を使用して Azure Identity をインストールします。
pip install azure-identity
前提条件
- Azure サブスクリプション
- Python 3.7 または Python 3 の最新バージョン (このライブラリは、有効期間終了バージョンをサポートしていません)
ローカル開発中に認証する
ローカルでコードをデバッグして実行する場合、開発者は独自のアカウントを使用して Azure サービスへの呼び出しを認証するのが一般的です。 Azure Identity ライブラリでは、ローカル開発を簡略化するための開発者ツールによる認証がサポートされています。
Visual Studio Code を使用した認証
Visual Studio Code を使用する開発者は、 Azure アカウント拡張機能 を使用してエディターを介して認証できます。 または VisualStudioCodeCredential を使用するDefaultAzureCredentialアプリでは、ローカルで実行するときに、このアカウントを使用してアプリの呼び出しを認証できます。
Visual Studio Code で認証するには、Azure アカウント拡張機能がインストールされていることを確認します。 インストールが完了したら、 コマンド パレット を開き、 Azure: Sign In コマンドを実行します。
これは、0.9.11 より新しい Azure アカウント拡張機能のバージョンでは機能しない既知の問題VisualStudioCodeCredentialです。 この問題に対する長期的な修正が進行中です。 それまでの間は、 Azure CLI を使用した認証を検討してください。
Azure CLI を使用した認証
DefaultAzureCredential と AzureCliCredential は、 Azure CLI にサインインしたユーザーとして認証できます。 Azure CLI にサインインするには、 を実行 az loginします。 既定の Web ブラウザーを使用するシステムでは、Azure CLI によってブラウザーが起動され、ユーザーが認証されます。
既定のブラウザーが使用できない場合は、 az login デバイス コード認証フローが使用されます。 このフローは、 を実行 az login --use-device-codeして手動で選択することもできます。
Azure Developer CLIを使用して認証する
IDE の外部でコーディングする開発者は、Azure Developer CLIを使用して認証することもできます。 その後、DefaultAzureCredential または AzureDeveloperCliCredential を使用するアプリケーションでこのアカウントを使用して、ローカルでの実行時にアプリケーションの呼び出しを認証できます。
Azure Developer CLIで認証を行うために、ユーザーは コマンド azd auth loginを実行できます。 既定の Web ブラウザーを使用してシステムで実行されているユーザーの場合、Azure Developer CLIはブラウザーを起動してユーザーを認証します。
既定の Web ブラウザーがないシステムの場合は、azd auth login --use-device-code コマンドでデバイス コード認証フローを使用します。
主要な概念
資格証明
資格情報はクラスの一種であり、サービス クライアントが要求を認証するために必要なデータを格納、または取得できます。 Azure SDK 全体のサービス クライアントは、構築時に資格情報インスタンスを受け入れ、その資格情報を使用して要求を認証します。
Azure Identity ライブラリでは、Azure AD での OAuth 認証に重点を置いています。 Azure AD アクセス トークンを取得できるさまざまな資格情報クラスが用意されています。 このライブラリのの一覧については、以下の資格情報クラスの資格情報クラスに関するセクションを参照してください。
DefaultAzureCredential
DefaultAzureCredential は、一般的な運用資格情報と開発資格情報を組み合わせたものであるため、Azure で実行されるほとんどのアプリケーションに適しています。 DefaultAzureCredential は、次のメカニズムを使用して認証を試みます。この順序で、成功すると停止します。
注:
DefaultAzureCredentialは、一般的なシナリオを適切な既定の動作で処理することで、ライブラリの使用を簡略化することを目的としています。 開発者がもっと多くの制御が必要な場合や、シナリオが既定の設定で提供されない場合は、他の資格情報の種類を使用する必要があります。
- 環境 -
DefaultAzureCredentialは、 環境変数 で指定されたアカウント情報を読み取り、それを使用して認証します。 - ワークロード ID - マネージド ID が有効になっているAzure Kubernetes Serviceにアプリケーションがデプロイされている場合、
DefaultAzureCredentialそのアプリケーションで認証が行われます。 - マネージド ID - マネージド ID が 有効になっている Azure ホストにアプリケーションがデプロイされている場合は、
DefaultAzureCredentialそれに対する認証が行われます。 - Azure CLI - ユーザーが Azure CLI
az loginコマンドを使用してサインインした場合、DefaultAzureCredentialそのユーザーとして認証されます。 - Azure PowerShell - ユーザーが Azure PowerShell の
Connect-AzAccountコマンドを使用してサインインした場合、DefaultAzureCredentialそのユーザーとして認証されます。 - Azure Developer CLI - 開発者が Azure Developer CLI
azd auth loginコマンドを使用して認証した場合、DefaultAzureCredentialはそのアカウントで認証されます。 - 対話型ブラウザー - 有効にすると、
DefaultAzureCredential既定のブラウザーを使用してユーザーが対話形式で認証されます。 この資格情報の種類は、既定では無効になっています。
に関する注意 VisualStudioCodeCredential
既知の問題により、 VisualStudioCodeCredential がトークン チェーンからDefaultAzureCredential削除されました。 今後のリリースで問題が解決されると、この変更は元に戻されます。
例
次の例を示します。
で認証する DefaultAzureCredential
を使用 DefaultAzureCredential するように環境を構成する方法の詳細については、クラスの リファレンス ドキュメントを参照してください。
この例では、 を使用して azure-storage-blob ライブラリから を認証するBlobServiceClient方法をDefaultAzureCredential示します。
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
default_credential = DefaultAzureCredential()
client = BlobServiceClient(account_url, credential=default_credential)
を使用して対話型認証を有効にする DefaultAzureCredential
対話型認証は、既定では でDefaultAzureCredential無効になっており、キーワード (keyword)引数を使用して有効にすることができます。
DefaultAzureCredential(exclude_interactive_browser_credential=False)
有効にすると、 DefaultAzureCredential 他の資格情報が使用できない場合は、システムの既定の Web ブラウザーを介して対話形式で認証されます。
のユーザー割り当てマネージド ID を指定する DefaultAzureCredential
多くの Azure ホストでは、ユーザー割り当てマネージド ID を割り当てることができます。 ユーザー割り当て ID を認証するように構成DefaultAzureCredentialするには、キーワード (keyword)引数をmanaged_identity_client_id使用します。
DefaultAzureCredential(managed_identity_client_id=client_id)
または、環境変数 AZURE_CLIENT_ID を ID のクライアント ID に設定します。
を使用してカスタム認証フローを定義する ChainedTokenCredential
DefaultAzureCredential は通常、Azure 用アプリケーションの開発を開始する最も迅速な方法です。 より高度なシナリオでは、 ChainedTokenCredential は、認証時に試行される複数の資格情報インスタンスを順番にリンクします。 トークンが提供されるか、エラーが原因で認証に失敗するまで、各チェーン資格情報が順番に試行されます。
次の例では、最初にマネージド ID を使用して認証を試みる資格情報を作成する方法を示します。 マネージド ID が使用できない場合、資格情報は Azure CLI を介した認証にフォールバックします。 この例では、azure-eventhub クライアント ライブラリの を使用EventHubProducerClientします。
from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential
managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)
client = EventHubProducerClient(namespace, eventhub_name, credential_chain)
非同期資格情報
このライブラリには、一連の非同期 API が含まれています。 azure.identity.aio で非同期資格情報を使用するには、まず、aiohttp などの非同期トランスポートをインストールする必要があります。 詳細については、 azure-core のドキュメントを参照してください。
非同期資格情報は、不要になったら閉じる必要があります。 各非同期資格情報は非同期コンテキスト マネージャーであり、非同期 close メソッドを定義します。 次に例を示します。
from azure.identity.aio import DefaultAzureCredential
# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()
# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
...
この例では、非同期 SecretClient 資格情報を使用して azure-keyvault-secrets から非同期を認証する方法を示します。
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)
マネージド ID のサポート
マネージド ID 認証 は、次の Azure サービスの または DefaultAzureCredential を ManagedIdentityCredential 介して直接サポートされます。
- Azure App Service と Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure Virtual Machines
- Azure 仮想マシン スケール セット
例
ユーザー割り当てマネージド ID で認証する
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)
システム割り当てマネージド ID で認証する
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)
クラウドの構成
資格情報の既定値は、Azure パブリック クラウドの Azure AD エンドポイントへの認証です。 Azure Governmentやプライベート クラウドなど、他のクラウド内のリソースにアクセスするには、 引数を使用して資格情報をauthority構成します。 AzureAuthorityHosts は、 既知のクラウドの機関を定義します。
from azure.identity import AzureAuthorityHosts
DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
クラウドの機関が に AzureAuthorityHosts一覧表示されていない場合は、その URL を明示的に指定できます。
DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")
引数を指定する authority 代わりに、環境変数を AZURE_AUTHORITY_HOST クラウドの機関の URL に設定することもできます。 この方法は、同じクラウドに対して認証するように複数の資格情報を構成する場合に便利です。
AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn
すべての資格情報でこの構成が必要なわけではありません。 などの AzureCliCredential開発ツールを使用して認証する資格情報は、そのツールの構成を使用します。 同様に、 は引数をauthority受け入れますが、VisualStudioCodeCredential既定では VS Code の "Azure: Cloud" 設定に一致する機関になります。
資格情報クラス
Azure でホストされるアプリケーションを認証する
| 資格情報 | 使用 |
|---|---|
DefaultAzureCredential |
Azure で実行されるアプリケーションの開発を迅速に開始するための簡素化された認証エクスペリエンスを提供します。 |
ChainedTokenCredential |
ユーザーが複数の資格情報で構成されるカスタム認証フローを定義できるようにします。 |
EnvironmentCredential |
環境変数で指定された資格情報を使用して、サービス プリンシパルまたはユーザーを認証します。 |
ManagedIdentityCredential |
Azure リソースのマネージド ID を認証します。 |
WorkloadIdentityCredential |
Kubernetes で Azure AD ワークロード ID を サポートします。 |
サービス プリンシパルを認証する
| 資格情報 | 使用 | リファレンス |
|---|---|---|
CertificateCredential |
証明書を使用してサービス プリンシパルを認証します。 | サービス プリンシパルの認証 |
ClientAssertionCredential |
署名されたクライアント アサーションを使用してサービス プリンシパルを認証します。 | |
ClientSecretCredential |
シークレットを使用してサービス プリンシパルを認証します。 | サービス プリンシパルの認証 |
ユーザーを認証する
| 資格情報 | 使用 | リファレンス |
|---|---|---|
AuthorizationCodeCredential |
以前に取得した承認コードを使用してユーザーを認証します。 | OAuth2 認証コード |
DeviceCodeCredential |
UI が制限されているデバイスでユーザーを対話形式で認証します。 | デバイス コード認証 |
InteractiveBrowserCredential |
既定のシステム ブラウザーを使用してユーザーを対話形式で認証します。 | OAuth2 認証コード |
OnBehalfOfCredential |
委任されたユーザー ID とアクセス許可を要求チェーンを介して伝達します。 | 代理認証 |
UsernamePasswordCredential |
ユーザー名とパスワードを使用してユーザーを認証します (多要素認証はサポートされていません)。 | ユーザー名とパスワードによる認証 |
開発ツールを使用した認証
| 資格情報 | 使用 | リファレンス |
|---|---|---|
AzureCliCredential |
Azure CLI を使用して開発環境で認証します。 | Azure CLI 認証 |
AzureDeveloperCliCredential |
Azure Developer CLIを使用して開発環境で認証します。 | Azure Developer CLI リファレンス |
AzurePowerShellCredential |
Azure PowerShellを使用して開発環境で認証します。 | Azure PowerShell認証 |
VisualStudioCodeCredential |
Visual Studio Code Azure アカウント拡張機能にサインインしたユーザーとして認証します。 | VS Code Azure Account の拡張機能 |
環境変数
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 |
秘密キーを含む PEM または PKCS12 証明書ファイルへのパス |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
証明書ファイルのパスワード (存在する場合) |
ユーザー名とパスワード
| 変数名 | 値 |
|---|---|
AZURE_CLIENT_ID |
Azure AD アプリケーションの ID |
AZURE_USERNAME |
ユーザー名 (通常はメール アドレス) |
AZURE_PASSWORD |
そのユーザーのパスワード |
構成は上記の順序で試行されます。 たとえば、クライアント シークレットと証明書の値が両方存在する場合、クライアント シークレットが使用されます。
トークンのキャッシュ
トークン キャッシュは、アプリが次の操作を可能にする Azure Identity ライブラリによって提供される機能です。
- メモリ内またはディスク (オプトイン) にトークンをキャッシュします。
- 回復性とパフォーマンスを向上させます。
- アクセス トークンを取得するために Azure AD に対して行われる要求の数を減らします。
Azure Identity ライブラリには、メモリ内と永続的なディスク キャッシュの両方が用意されています。 詳細については、 トークン キャッシュに関するドキュメントを参照してください。
トラブルシューティング
さまざまな障害シナリオを診断する方法の詳細については、 トラブルシューティング ガイド を参照してください。
エラー処理
資格情報は、必要なデータや状態がないため、認証を試みることができないときに発生 CredentialUnavailableError します。 たとえば、EnvironmentCredential では、が不完全な場合に、この例外が発生します。
資格情報で認証できなかった場合は、azure.core.exceptions.ClientAuthenticationError が発生します。 ClientAuthenticationError には、 message 認証が失敗した理由を示す 属性があります。 または ChainedTokenCredentialによってDefaultAzureCredential発生すると、メッセージはチェーン内の各資格情報からエラー メッセージを収集します。
特定の Azure AD エラーの処理の詳細については、Azure AD エラー コードのドキュメントを参照してください。
ログの記録
このライブラリでは、ログ記録に標準 のログ ライブラリが使用されます。 資格情報は、HTTP セッション (URL、ヘッダーなど) を含む基本情報を INFO レベルでログに記録します。 これらのログ エントリには、認証シークレットは含まれません。
要求/応答本文やヘッダー値を含む詳細な DEBUG レベルのログは、既定では有効になっていません。 引数を使用して logging_enable 有効にすることができます。 次に例を示します。
credential = DefaultAzureCredential(logging_enable=True)
注意: 資格情報からのデバッグ レベルのログには、機密情報が含まれています。 これらのログは、アカウントのセキュリティを損なわないように保護する必要があります。
次のステップ
クライアント ライブラリのサポート
Azure AD 認証をサポートする Azure SDK リリース ページ に記載されているクライアントライブラリと管理ライブラリは、このライブラリからの資格情報を受け入れます。 これらのライブラリの使用方法の詳細については、リリース ページからリンクされているドキュメントを参照してください。
既知の問題
このライブラリでは、 Azure AD B2C はサポートされていません。
その他の未解決の問題については、ライブラリの GitHub リポジトリを参照してください。
フィードバックの提供
バグが発生した場合、または提案がある場合は、 問題を開きます。
共同作成
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。
pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。
このプロジェクトは、「Microsoft のオープン ソースの倫理規定」を採用しています。 詳細については、倫理規定についてよくあるご質問を参照するか、opencode@microsoft.com 宛てにご質問またはコメントをお送りください。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示