適用於 JavaScript 的 Azure 身分識別用戶端連結庫 - 4.1.0 版
Azure 身分識別連結庫透過一組方便的 TokenCredential 實作，提供 Microsoft Entra ID (先前稱為 Azure Active Directory) 令牌驗證。
如需各種認證的範例，請參閱 Azure 身分識別範例頁面。
重要連結：
- 原始程式碼 \(英文\)
- 套件 (npm)
- API 參考檔
- Microsoft Entra ID 文件
- 範例
開始使用
從 v1 移轉至 v2 @azure/identity
如果您使用 的 @azure/identityv1，請參閱更新至 v2 的 移轉指南 。
目前支援的環境
- Node.js 的 LTS 版本
- 注意： 如果您的應用程式在 Node.js v8 或更低版本上執行，而且您無法將 Node.js 版本升級至最新的穩定版本，請將您的
@azure/identity相依性釘選到 1.1.0 版。
- 注意： 如果您的應用程式在 Node.js v8 或更低版本上執行，而且您無法將 Node.js 版本升級至最新的穩定版本，請將您的
- Safari、Chrome、Edge 和 Firefox 的最新版本。
- 注意：在此連結庫中導出的不同認證之間，
InteractiveBrowserCredential是唯一在瀏覽器中支持的認證。
- 注意：在此連結庫中導出的不同認證之間，
如需詳細資訊，請參閱我們的支援原則。
安裝套件
使用 npm 安裝 Azure 身分識別：
npm install --save @azure/identity
Prerequisites
- Azure 訂用帳戶。
- 選用：Azure CLI 和/或 Azure PowerShell 也可用於在開發環境中驗證和管理帳戶角色。
@azure/identity 的使用時機
所 @azure/identity 公開的認證類別著重於提供最直接的方式，在本機、開發環境和生產環境中驗證 Azure SDK 用戶端。 我們的目標是簡單且合理的驗證通訊協議支援，以涵蓋 Azure 上大部分可能的驗證案例。 我們正積極擴充以涵蓋更多案例。 如需提供之認證的完整清單，請參閱 認證類別一 節。
Node.js 支援 所提供的 @azure/identity 所有認證類型。 針對瀏覽器， InteractiveBrowserCredential 是用於基本身份驗證案例的認證類型。
大部分認證類型都是 @azure/identity 使用 適用於 JavaScript 的 Microsoft 驗證連結庫 (MSAL.js) 。 具體而言，我們使用 v2 MSAL.js 連結庫，其使用 OAuth 2.0 授權碼流程搭配 PKCE ，且 符合 OpenID 規範。 雖然 @azure/identity 著重於簡單性，但 MSAL.js 連結庫，例如 @azure/msal-common、 @azure/msal-node 和 @azure/msal-browser，其設計目的是為 Azure 支援的驗證通訊協定提供強固支援。
使用其他專案時的時機
認證 @azure/identity 類型是 @azure/core-auth 類別的實作 TokenCredential 。 基本上，任何具有 getToken 滿足 getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> 之方法的對象都會以的形式 TokenCredential運作。 這表示開發人員可以撰寫自己的認證類型，以支援 未涵蓋的 @azure/identity驗證案例。 若要深入瞭解，請參閱 自定義認證。
雖然我們的認證類型支援許多進階案例，但開發人員可能會想要完全控制驗證通訊協定。 針對該使用案例，我們建議直接使用 適用於 JavaScript 的 Microsoft 驗證連結庫 (MSAL.js) 。 您可以透過下列連結進一步閱讀：
- 我們會在 [Azure 身分識別範例] 頁面上建立一些進階的使用案例
@azure/identity。- 在此，我們特別有 [ 進階範例 ] 區段。
- 我們也有一個區段，說明如何 直接使用 MSAL 進行驗證。
如需瀏覽器中的進階驗證工作流程，我們有一節示範如何使用 @azure/msal-browser 連結庫直接驗證 Azure SDK 用戶端。
在開發環境中驗證用戶端
雖然我們建議您在生產應用程式中使用受控識別或服務主體驗證，但開發人員在本機偵錯和執行程式碼時，通常會使用自己的帳戶來驗證對 Azure 服務的呼叫。 有數個開發人員工具可供您在開發環境中執行此驗證。
透過 Azure Developer CLI 進行驗證
在 IDE 外部撰寫程式代碼的開發人員也可以使用 [Azure Developer CLI][azure_developer_cli] 進行驗證。 之後，使用 DefaultAzureCredential 或 AzureDeveloperCliCredential 的應用程式便可在本機執行時，利用此帳戶來驗證應用程式中的呼叫。
若要使用 [Azure Developer CLI][azure_developer_cli] 進行驗證，使用者可以執行 命令 azd auth login。 對於使用預設網頁瀏覽器在系統上執行的使用者，Azure Developer CLI 將會啟動瀏覽器來驗證使用者。
針對沒有預設網頁瀏覽器的系統，azd auth login --use-device-code 命令會採用裝置程式碼驗證流程。
透過 Azure CLI 進行驗證
無論是 AzureCliCredential直接或透過 DefaultAzureCredential的應用程式，都可以使用 Azure CLI 帳戶在本機執行時驗證應用程式中的呼叫。
若要利用 Azure CLI 進行驗證，使用者可執行命令 az login。 針對使用預設網路瀏覽器在系統上執行的使用者，Azure cli 會啟動瀏覽器來驗證使用者。
針對沒有預設網頁瀏覽器的系統，az login 命令會採用裝置程式碼驗證流程。 使用者也可以強制 Azure CLI 採用裝置程式碼流程，而不是指定 --use-device-code 引數來啟動瀏覽器。
透過 Azure PowerShell 進行驗證
無論是AzurePowerShellCredential直接或透過DefaultAzureCredential的應用程式，都可以使用連線到 Azure PowerShell 帳戶，在本機執行時驗證應用程式中的呼叫。
若要向 Azure PowerShell 用戶進行驗證，可以執行 Connect-AzAccount Cmdlet。 根據預設， Connect-AzAccount ike Azure CLI 會啟動預設網頁瀏覽器來驗證使用者帳戶。
如果會話中不支援互動式驗證，則 -UseDeviceAuthentication 自變數會強制 Cmdlet 改用裝置程式代碼驗證流程，類似於 Azure CLI 認證中的對應選項。
透過 Visual Studio Code 進行驗證
使用 Visual Studio Code的開發人員可以使用 Azure 帳戶擴充功能，透過編輯器進行驗證。 然後，使用 VisualStudioCodeCredential 的應用程式可以在本機執行時，使用此帳戶來驗證其應用程式中的呼叫。
若要在 Visual Studio Code 中驗證，請確定已安裝 Azure 帳戶擴充功能。 安裝之後，開啟 命令選擇區 並執行 Azure：登入 命令。
此外，請使用 @azure/identity-vscode 外掛程式套件。 此套件提供的 VisualStudioCodeCredential 相依性，並加以啟用。 請參閱 外掛程式。
已知問題VisualStudioCodeCredential不適用於 0.9.11 之前的 Azure 帳戶擴充功能版本。 此問題的長期修正正在進行中。 同時，請考慮 透過 Azure CLI 進行驗證。
在瀏覽器中驗證用戶端
為了在網頁瀏覽器中驗證 Azure SDK 用戶端，我們提供 InteractiveBrowserCredential，其可設定為使用重新導向或彈出視窗來完成驗證流程。 您必須先在 Web 應用程式的 Azure 入口網站 中建立 Azure App 註冊。
重要概念
如果這是您第一次使用 @azure/identity 或 Microsoft Entra ID，請先閱讀 Using @azure/identity with Microsoft Entra ID。 本檔可讓您更深入了解平臺，以及如何正確設定 Azure 帳戶。
認證
認證指的是包含或可取得服務用戶端所需資料以驗證要求的類別。 在建構認證時，Azure SDK 上的服務用戶端會接受認證。 服務用戶端會使用這些認證來驗證對服務的要求。
Azure 身分識別連結庫著重於具有 Microsoft Entra ID 的 OAuth 驗證，並提供各種認證類別，能夠取得 Microsoft Entra 令牌來驗證服務要求。 此程式庫中的所有認證類別都是 TokenCredential 抽象類別的實作，其中的任何一個類別都可用於建構可使用 TokenCredential 進行驗證的服務用戶端。
請參閱認證類別。
DefaultAzureCredential
DefaultAzureCredential適用於應用程式最終會在 Azure 中執行的大部分案例。 這是因為 會 DefaultAzureCredential 結合在部署時經常用來驗證的認證，以及用來在開發環境中進行驗證的認證。
注意：
DefaultAzureCredential旨在藉由處理具有合理預設行為的常見案例來簡化 SDK 用戶入門。 想要更多控制或其案例未透過預設設定來提供的開發人員應該使用其他認證類型。
如果從 Node.js 使用，將會 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使用該帳戶進行驗證。
接續原則
從 3.3.0 版開始， DefaultAzureCredential 不論先前的開發人員認證發生任何錯誤，都會嘗試使用所有開發人員認證進行驗證，直到成功為止。 例如，開發人員認證可能會嘗試取得令牌並失敗，因此 DefaultAzureCredential 會繼續前往流程中的下一個認證。 如果已部署的服務認證能夠嘗試擷取令牌，但未收到令牌，則會停止擲回例外狀況的流程。
這可讓您在計算機上嘗試所有開發人員認證，同時具有可預測的部署行為。
附註 VisualStudioCodeCredential
由於 已知問題， VisualStudioCodeCredential 已從 DefaultAzureCredential 令牌鏈結中移除。 當問題在未來版本中解決時，將會還原這項變更。
外掛程式
適用於 JavaScript 的 Azure 身分識別提供外掛程式 API，可讓我們透過個別 的外掛程式套件提供特定功能。 套件會 @azure/identity () useIdentityPlugin 匯出最上層函式，以用來啟用外掛程式。 我們提供兩個外掛程式套件：
@azure/identity-broker，可透過原生訊息代理程式提供代理驗證支援，例如 Web 帳戶管理員。@azure/identity-cache-persistence，它會使用操作系統所提供的原生安全儲存系統，在 Node.js 中提供永續性令牌快取。 此外掛程式允許跨會話保存快access_token取值，這表示只要有快取的令牌可用，互動式登入流程就不需要重複。
範例
您可在 Azure 身分識別範例頁面中參考更多使用各種認證的範例
使用進行驗證 DefaultAzureCredential
此範例示範如何使用 DefaultAzureCredential從 @azure/keyvault-keys 用戶端連結庫驗證 KeyClient 。
// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.
// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";
// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";
// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();
// Create authenticated client
const client = new KeyClient(vaultUrl, credential);
使用 指定使用者指派的受控識別 DefaultAzureCredential
相對常見的案例涉及使用使用者指派的 Azure 資源受控識別進行驗證。 探索 使用DefaultAzureCredential驗證使用者指派受控識別的範例 ，以瞭解這是如何使用環境變數或在程式碼中設定的相對直接工作。
使用 ChainedTokenCredential 定義自訂驗證流程
雖然 DefaultAzureCredential 通常是開發 Azure 應用程式最快速的方式，但進階使用者可能會希望在驗證時自訂認證。 ChainedTokenCredential 可供使用者結合多個認證實例，以定義自訂的認證鏈結。 此範例示範如何建立 ，ChainedTokenCredential其會嘗試使用 兩個不同設定的 ClientSecretCredential實例進行驗證，然後從 @azure/keyvault-keys 驗證 KeyClient ：
import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);
// The chain can be used anywhere a credential is required
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);
受控識別支援
受控 識別驗證 可 DefaultAzureCredential 透過 或 ManagedIdentityCredential 認證類別直接支援下列 Azure 服務：
- Azure App Service 和 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure 虛擬機器
- Azure 虛擬機器 擴展集
如需如何使用受控識別進行驗證的範例，請參閱 範例。
Cloud configuration
認證預設為向 Azure 公用雲端 Microsoft Entra 端點進行驗證。 若要存取其他雲端中的資源，例如 Azure Government 或私人雲端，請使用建構函式中的 自變數來設定認證authorityHost。 介面 AzureAuthorityHosts 會定義已知雲端的授權單位。 針對美國政府雲端，您可以用這種方式具現化認證：
import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
"<YOUR_TENANT_ID>",
"<YOUR_CLIENT_ID>",
"<YOUR_CLIENT_SECRET>",
{
authorityHost: AzureAuthorityHosts.AzureGovernment,
}
);
並非所有認證都需要此設定。 透過開發工具進行驗證的認證，例如 AzureCliCredential，會使用該工具的組態。 同樣地，VisualStudioCodeCredential接受自authorityHost變數，但預設為authorityHost相符 Visual Studio Code 的 Azure：雲端設定。
認證類別
驗證 Azure 裝載的應用程式
| 認證 | 使用狀況 | 範例 |
|---|---|---|
DefaultAzureCredential |
提供簡化的驗證體驗，以快速開始在 Azure 中開發應用程式。 | 範例 |
ChainedTokenCredential |
允許使用者定義撰寫多個認證的自訂驗證流程。 | 範例 |
EnvironmentCredential |
透過環境變數中指定的認證資訊來驗證服務主體或使用者。 | 範例 |
ManagedIdentityCredential |
驗證 Azure 資源的受控識別。 | 範例 |
WorkloadIdentityCredential |
支援 Kubernetes 上的 Microsoft Entra 工作負載 ID。 | 範例 |
驗證服務主體
| 認證 | 使用狀況 | 範例 | 參考 |
|---|---|---|---|
ClientAssertionCredential |
使用已簽署的客戶端判斷提示來驗證服務主體。 | 範例 | 服務主體驗證 |
ClientCertificateCredential |
使用憑證驗證服務主體。 | 範例 | 服務主體驗證 |
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 |
Microsoft Entra 應用程式的識別碼 |
AZURE_TENANT_ID |
應用程式 Microsoft Entra 租用戶的識別碼 |
AZURE_CLIENT_SECRET |
其中一個應用程式的用戶端密碼 |
具有憑證的服務主體
| 變數名稱 | 值 |
|---|---|
AZURE_CLIENT_ID |
Microsoft Entra 應用程式的識別碼 |
AZURE_TENANT_ID |
應用程式 Microsoft Entra 租用戶的識別碼 |
AZURE_CLIENT_CERTIFICATE_PATH |
PEM 編碼憑證檔案的路徑，包括私鑰 |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
憑證檔案的密碼，如果有的話 |
使用者名稱和密碼
| 變數名稱 | 值 |
|---|---|
AZURE_CLIENT_ID |
Microsoft Entra 應用程式的識別碼 |
AZURE_TENANT_ID |
應用程式 Microsoft Entra 租用戶的識別碼 |
AZURE_USERNAME |
使用者名稱 (通常是電子郵件地址) |
AZURE_PASSWORD |
該使用者的密碼 |
系統會依上述順序嘗試進行設定。 例如，如果用戶端同時具有密碼和憑證的值，則系統會採用用戶端密碼。
持續性存取評估
從 3.3.0 版開始，可以依要求存取 持續存取評估 (CAE) 保護的資源。 這可以使用 API 來啟用GetTokenOptions.enableCae(boolean)。 開發人員認證不支援 CAE。
權杖快取
令牌快取是 Azure 身分識別連結庫所提供的功能，可讓應用程式：
- 在記憶體 (預設) 和磁碟上的快取令牌， (加入加入) 。
- 改善復原能力和效能。
- 減少對 Microsoft Entra ID 提出以取得存取令牌的要求數目。
Azure 身分識別連結庫提供記憶體內部和永續性磁碟快取。 如需詳細資訊，請參閱 令牌快取檔。
代理驗證
驗證代理程式是在使用者的計算機上執行，並管理已連線帳戶的驗證交握和令牌維護的應用程式。 目前僅支援 Windows Web 帳戶管理員 (WAM) 。 若要啟用支援，請使用 @azure/identity-broker 套件。 如需使用WAM進行驗證的詳細資訊，請參閱 訊息代理程式外掛程式檔。
疑難排解
如需疑難解答的協助，請參閱 疑難解答指南。
後續步驟
閱讀文件
您可在我們的文件網站中查找此程式庫的 API 文件。
用戶端程式庫支援
Azure SDK 發行頁面上所列的用戶端和管理連結庫，可支援 Microsoft Entra 驗證接受來自此連結庫的認證。 深入瞭解在檔中使用這些連結庫，其鏈接自發行頁面。
已知問題
Azure AD B2C 支援
此連結庫不支援 Azure AD B2C 服務。
如需其他開啟的問題，請參閱連結庫的 GitHub 存放庫。
提供意見反應
如果您遇到錯誤或有任何建議，請提出問題。
參與
如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應