適用于 Python 的 Azure 身分識別用戶端程式庫 - 1.14.1 版
Azure 身分識別程式庫提供 Azure Active Directory (Azure AD) Azure SDK 的權杖驗證支援。 它提供一組實作，可用來建構支援 Azure AD 權杖驗證的 TokenCredential Azure SDK 用戶端。
| 原始程式碼套件 (PyPI) | 套件 (Conda) | API 參考檔 | Azure AD 檔
開始使用
安裝套件
使用 pip 安裝 Azure 身分識別：
pip install azure-identity
必要條件
- Azure 訂用帳戶
- Python 3.7 或最新版本的 Python 3 (此程式庫不支援生命週期結束版本)
在本機開發期間進行驗證
在本機偵錯和執行程式碼時，開發人員通常會使用自己的帳戶來驗證對 Azure 服務的呼叫。 Azure 身分識別程式庫支援透過開發人員工具進行驗證，以簡化本機開發。
透過Visual Studio Code進行驗證
使用 Visual Studio Code 的開發人員可以使用Azure 帳戶擴充功能，透過編輯器進行驗證。 DefaultAzureCredential接著，使用 或 VisualStudioCodeCredential 的應用程式可以在本機執行時，使用此帳戶來驗證其應用程式中的呼叫。
若要在 Visual Studio Code 進行驗證，請確定已安裝 Azure 帳戶擴充功能。 安裝之後，開啟 命令選擇區 並執行 Azure：登入 命令。
已知問題VisualStudioCodeCredential 不適用於0.9.11之前的Azure 帳戶擴充功能版本。 此問題的長期修正正在進行中。 同時，請考慮 透過 Azure CLI 進行驗證。
透過 Azure CLI 進行驗證
DefaultAzureCredential 和 AzureCliCredential 可以在使用者登入 Azure CLI時進行驗證。 若要登入 Azure CLI，請執行 az login 。 在具有預設網頁瀏覽器的系統上，Azure CLI 會啟動瀏覽器來驗證使用者。
當沒有預設瀏覽器可用時， az login 將會使用裝置程式碼驗證流程。 執行 也可以手動 az login --use-device-code 選取此流程。
透過Azure Developer CLI進行驗證
在 IDE 外部撰寫程式碼的開發人員也可以使用Azure Developer CLI進行驗證。 之後，使用 DefaultAzureCredential 或 AzureDeveloperCliCredential 的應用程式便可在本機執行時，利用此帳戶來驗證應用程式中的呼叫。
若要使用Azure Developer CLI進行驗證，使用者可以執行 命令 azd auth login 。 對於以預設網頁瀏覽器在系統上執行的使用者，Azure Developer CLI會啟動瀏覽器來驗證使用者。
針對沒有預設網頁瀏覽器的系統，azd auth login --use-device-code 命令會採用裝置程式碼驗證流程。
重要概念
認證
認證是類別，包含或可以取得服務用戶端驗證要求所需的資料。 在建構認證時，Azure SDK 上的服務用戶端會接受認證實例，並使用該認證來驗證要求。
Azure 身分識別程式庫著重于使用 Azure AD 進行 OAuth 驗證。 它提供各種認證類別，可取得 Azure AD 存取權杖。 如需此程式庫認證類別的清單，請參閱下面的認證認證類別一節。
DefaultAzureCredential
DefaultAzureCredential 適用于在 Azure 中執行的大部分應用程式，因為它結合了常見的生產認證與開發認證。 DefaultAzureCredential 會依此順序嘗試透過下列機制進行驗證，並在一個成功時停止：
注意：
DefaultAzureCredential旨在藉由處理具有合理預設行為的常見案例來簡化開始使用程式庫。 想要更多控制或其案例未透過預設設定來提供的開發人員應該使用其他認證類型。
- 環境 -
DefaultAzureCredential將會讀取透過指定的帳號資訊，並使用它進行驗證。 - 工作負載識別- 如果應用程式部署至已啟用受控識別的Azure Kubernetes Service，
DefaultAzureCredential將會使用它進行驗證。 - 受控識別 - 如果應用程式部署至已啟用受控識別的 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 請參閱 類別的 參考檔。
此範例示範如何使用 DefaultAzureCredential 從azure-storage-blob程式庫驗證 BlobServiceClient 。
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
default_credential = DefaultAzureCredential()
client = BlobServiceClient(account_url, credential=default_credential)
使用 啟用互動式驗證 DefaultAzureCredential
根據預設， DefaultAzureCredential 互動式驗證會在 中停用，而且可以使用關鍵字引數來啟用：
DefaultAzureCredential(exclude_interactive_browser_credential=False)
啟用時，當沒有其他認證可用時， DefaultAzureCredential 會回復為透過系統的預設網頁瀏覽器以互動方式進行驗證。
指定使用者指派的受控識別 DefaultAzureCredential
許多 Azure 主機都允許指派使用者指派的受控識別。 若要設定 DefaultAzureCredential 來驗證使用者指派的身分識別，請使用 managed_identity_client_id 關鍵字引數：
DefaultAzureCredential(managed_identity_client_id=client_id)
或者，將環境變數 AZURE_CLIENT_ID 設定為身分識別的用戶端識別碼。
使用 ChainedTokenCredential 定義自訂驗證流程
DefaultAzureCredential 通常是開始開發 Azure 應用程式的最快速方式。 針對更進階的案例， ChainedTokenCredential 會在驗證時循序連結多個認證實例。 它會接著嘗試每個鏈結的認證，直到有一個提供權杖或因為錯誤而無法進行驗證為止。
下列範例示範如何建立會先嘗試使用受控識別進行驗證的認證。 當受控識別無法使用時，認證會回復為透過 Azure CLI 進行驗證。 此範例會使用 EventHubProducerClient來自 azure-eventhub 用戶端程式庫的 。
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 核心檔。
不再需要非同步認證時，應該關閉。 每個非同步認證都是非同步內容管理員，並定義非同步 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)
受控識別支援
透過 DefaultAzureCredential 或 ManagedIdentityCredential 直接支援下列 Azure 服務的受控識別驗證：
- Azure App Service 和 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure 虛擬機器
- Azure 虛擬機器擴展集
範例
使用使用者指派的受控識別進行驗證
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)
使用系統指派的受控識別進行驗證
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)
Cloud configuration
認證預設為向 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 ，會使用該工具的組態。 同樣地， VisualStudioCodeCredential 接受自 authority 變數，但預設為符合 VS Code 的 「Azure： Cloud」設定的授權單位。
認證類別
驗證 Azure 裝載的應用程式
| 認證 | 使用方式 |
|---|---|
DefaultAzureCredential |
提供簡化的驗證體驗，以快速開始在 Azure 中開發應用程式。 |
ChainedTokenCredential |
允許使用者定義撰寫多個認證的自訂驗證流程。 |
EnvironmentCredential |
透過環境變數中指定的認證資訊來驗證服務主體或使用者。 |
ManagedIdentityCredential |
驗證 Azure 資源的受控識別。 |
WorkloadIdentityCredential |
支援 Kubernetes 上的 Azure AD 工作負載身分識別 。 |
驗證服務主體
| 認證 | 使用方式 | 參考 |
|---|---|---|
CertificateCredential |
使用憑證驗證服務主體。 | 服務主體驗證 |
ClientAssertionCredential |
使用已簽署的用戶端判斷提示來驗證服務主體。 | |
ClientSecretCredential |
使用密碼驗證服務主體。 | 服務主體驗證 |
驗證使用者
| 認證 | 使用方式 | 參考 |
|---|---|---|
AuthorizationCodeCredential |
使用先前取得的授權碼來驗證使用者。 | OAuth2 驗證碼 |
DeviceCodeCredential |
在 UI 受限的裝置上以互動方式驗證使用者。 | 裝置程式碼驗證 |
InteractiveBrowserCredential |
透過預設系統瀏覽器以互動方式驗證使用者。 | OAuth2 驗證碼 |
OnBehalfOfCredential |
透過要求鏈結傳播委派的使用者身分識別和許可權。 | 代理者驗證 |
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 帳戶擴充功能 |
環境變數
DefaultAzureCredential 和 EnvironmentCredential 可以使用環境變數進行設定。 每一種驗證類型都需要特定變數的值：
具備密碼的服務主體
| 變數名稱 | 值 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 應用程式的識別碼 |
AZURE_TENANT_ID |
應用程式 Azure AD 租使用者的識別碼 |
AZURE_CLIENT_SECRET |
其中一個應用程式的用戶端密碼 |
具有憑證的服務主體
| 變數名稱 | 值 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 應用程式的識別碼 |
AZURE_TENANT_ID |
應用程式 Azure AD 租使用者的識別碼 |
AZURE_CLIENT_CERTIFICATE_PATH |
PEM 或 PKCS12 憑證檔案的路徑，包括私密金鑰 |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
憑證檔案的密碼，如果有的話 |
使用者名稱和密碼
| 變數名稱 | 值 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 應用程式的識別碼 |
AZURE_USERNAME |
使用者名稱 (通常是電子郵件地址) |
AZURE_PASSWORD |
該使用者的密碼 |
系統會依上述順序嘗試進行設定。 例如，如果用戶端同時具有密碼和憑證的值，則系統會採用用戶端密碼。
權杖快取
權杖快取是由 Azure 身分識別程式庫所提供的功能，可讓應用程式：
- 在記憶體中快取權杖 (預設) 或磁片 (加入宣告) 。
- 改善復原能力和效能。
- 減少對 Azure AD 提出的要求數目，以取得存取權杖。
Azure 身分識別程式庫同時提供記憶體內部和永續性磁片快取。 如需詳細資訊，請參閱 權杖快取檔。
疑難排解
如需如何診斷各種失敗案例的詳細資訊，請參閱 疑難排解指南 。
錯誤處理
認證在無法嘗試驗證時引發 CredentialUnavailableError ，因為它們缺少必要的資料或狀態。 例如，EnvironmentCredential會在設定不完整時引發此例外狀況。
認證無法驗證時會引發 azure.core.exceptions.ClientAuthenticationError。 ClientAuthenticationErrormessage具有 屬性，描述驗證失敗的原因。 當 或 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)」，宣告您有權且確實授與我們使用投稿的權利。 如需詳細資料，請前往 https://cla.microsoft.com 。
當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用 CLA 在所有存放庫上執行此動作一次。
此專案採用了 Microsoft 開放原始碼管理辦法。 如需詳細資訊，請參閱管理辦法常見問題集，如有其他問題或意見，請連絡 opencode@microsoft.com。
