適用於 JavaScript 的 Azure 身分識別用戶端連結庫 - 4.4.1 版
Azure 身分識別連結庫會透過一組方便的 TokenCredential 實作，提供 Microsoft Entra ID （先前稱為 Azure Active Directory） 令牌驗證。
如需各種認證的範例，請參閱 Azure 身分識別範例頁面。
主要連結：
開始
目前支持的環境
-
LTS 版本的 Node.js
-
注意： 如果您的應用程式在 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
先決條件
- 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 連結庫，其會搭配 PKCE 使用 @azure/identity 著重於簡單性，但 MSAL.js 連結庫，例如 @azure/msal-common、@azure/msal-node，以及 @azure/msal-browser設計來為 Azure 支援的驗證通訊協定提供穩固的支援。
使用其他專案時的時機
@azure/identity 認證類型是 @azure/core-authTokenCredential 類別的實作。 原則上，任何具有滿足 getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> 之 getToken 方法的對象都會以 TokenCredential的形式運作。 這表示開發人員可以撰寫自己的認證類型，以支援 @azure/identity未涵蓋的驗證案例。 若要深入瞭解，請參閱 自定義認證。
雖然我們的認證類型支援許多進階案例，但開發人員可能想要完全控制驗證通訊協定。 針對該使用案例，我們建議直接使用適用於 JavaScript 的 Microsoft 驗證連結庫 （MSAL.js）。 您可以透過下列連結進一步閱讀：
- 我們會在 Azure 身分識別範例 頁面上描繪
@azure/identity的一些進階使用案例。- 在那裡，我們特別有 進階範例 一節。
- 我們也有一個區段，示範如何直接
使用 MSAL 進行驗證。
針對瀏覽器中的進階驗證工作流程，我們有一個區段，示範如何使用 @azure/msal-browser 連結庫直接驗證 Azure SDK 用戶端。
在開發環境中驗證用戶端
雖然我們建議在 Azure 裝載的應用程式中使用受控識別，但開發人員通常會在本機偵錯和執行程式碼時，使用自己的帳戶來驗證對 Azure 服務的呼叫。 有數個開發人員工具可用來在開發環境中執行此驗證。
透過 Azure 開發人員 CLI 進行驗證
在 IDE 外部撰寫程式代碼的開發人員也可以使用 azure 開發人員 CLI 來驗證 DefaultAzureCredential 或 AzureDeveloperCliCredential 的應用程式，接著可以在本機執行時，使用此帳戶來驗證其應用程式中的呼叫。
若要使用 Azure Developer CLI進行驗證，使用者可以執行 命令 azd auth login。 對於使用預設網頁瀏覽器在系統上執行的使用者，Azure 開發人員 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。 根據預設，如同 Azure CLI，Connect-AzAccount 會啟動預設網頁瀏覽器來驗證用戶帳戶。
如果會話中不支援互動式驗證，則 -UseDeviceAuthentication 自變數會強制 Cmdlet 改用裝置程式代碼驗證流程，類似於 Azure CLI 認證中的對應選項。
透過 Visual Studio Code 進行驗證
使用 Visual Studio Code 的開發人員可以使用 Azure 帳戶擴充功能 透過編輯器進行驗證。 接著，使用 VisualStudioCodeCredential 的應用程式可以在本機執行時，使用此帳戶來驗證其應用程式中的呼叫。
若要在 Visual Studio Code 中驗證，請確定已安裝 Azure 帳戶擴充功能。 安裝之後，開啟 命令選擇區，然後執行 Azure：登入 命令。
此外，請使用 @azure/identity-vscode 外掛程式套件。 此套件提供 VisualStudioCodeCredential 的相依性，並加以啟用。 請參閱 外掛程式。
在瀏覽器中驗證用戶端
為了在網頁瀏覽器中驗證 Azure SDK 用戶端，我們提供 InteractiveBrowserCredential，其可設定為使用重新導向或快顯來完成驗證流程。 您必須先在 Azure 入口網站中為 Web 應用程式建立 Azure 應用程式註冊
重要概念
如果這是您第一次使用 @azure/identity 或 Microsoft Entra 識別符，請先閱讀 使用 @azure/identity 搭配 Microsoft Entra ID。 本檔可讓您更深入了解平臺，以及如何正確設定您的 Azure 帳戶。
憑據
認證是類別，其中包含或可取得服務客戶端驗證要求所需的數據。 跨 Azure SDK 的服務用戶端會在建構認證時接受認證。 服務用戶端會使用這些認證來驗證服務的要求。
Azure 身分識別連結庫著重於具有 Microsoft Entra 識別符的 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);
受控識別支援
受控識別驗證 可透過下列 Azure 服務直接 DefaultAzureCredential 或 ManagedIdentityCredential 認證類別來支援：
- Azure App Service 和 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure 虛擬機
- Azure 虛擬機擴展集
如需如何使用受控識別進行驗證的範例，請參閱 範例。
雲端設定
認證預設為向 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 自變數，但預設為符合 Visual Studio Code Azure 的 authorityHost：雲端 設定。
認證類別
驗證 Azure 裝載的應用程式
| 憑據 | 用法 | 例 |
|---|---|---|
DefaultAzureCredential |
提供簡化的驗證體驗，以快速開始在 Azure 中執行應用程式。 | 範例 |
ChainedTokenCredential |
允許使用者定義組成多個認證的自訂驗證流程。 | 範例 |
EnvironmentCredential |
透過環境變數中指定的認證資訊來驗證服務主體或使用者。 | 範例 |
ManagedIdentityCredential |
驗證 Azure 資源的受控識別。 | 範例 |
WorkloadIdentityCredential |
支援 Kubernetes 上的 Microsoft Entra 工作負載標識碼。 | 範例 |
驗證服務主體
| 憑據 | 用法 | 例 | 參考 |
|---|---|---|---|
AzurePipelinesCredential |
支援 Azure Pipelines 上的 Microsoft Entra 工作負載標識碼。 | 範例 | |
ClientAssertionCredential |
使用已簽署的客戶端判斷提示來驗證服務主體。 | 範例 | 服務主體驗證 |
ClientCertificateCredential |
使用憑證驗證服務主體。 | 範例 | 服務主體驗證 |
ClientSecretCredential |
使用秘密驗證服務主體。 | 範例 | 服務主體驗證 |
驗證使用者
| 憑據 | 用法 | 例 | 參考 |
|---|---|---|---|
AuthorizationCodeCredential |
使用先前取得的授權碼來驗證使用者。 | 範例 | OAuth2 驗證碼 |
DeviceCodeCredential |
以互動方式驗證裝置上具有有限UI的使用者。 | 範例 | 裝置程式代碼驗證 |
InteractiveBrowserCredential |
以互動方式向預設系統瀏覽器驗證使用者。 如需詳細資訊，請參閱這裡 。 | 範例 | OAuth2 驗證碼 |
OnBehalfOfCredential |
透過要求鏈結傳播委派的使用者身分識別和許可權 | 代理驗證 | |
UsernamePasswordCredential |
使用使用者名稱和密碼來驗證使用者。 | 範例 | 使用者名稱 + 密碼驗證 |
透過開發工具進行驗證
| 憑據 | 用法 | 例 | 參考 |
|---|---|---|---|
AzureCliCredential |
使用 Azure CLI 在開發環境中進行驗證。 | 範例 | Azure CLI 驗證 |
AzureDeveloperCliCredential |
在開發環境中使用 Azure 開發人員 CLI 中已啟用的使用者或服務主體進行驗證。 | Azure 開發人員 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） 保護的資源。 這可以使用 GetTokenOptions.enableCae(boolean) API來啟用。 開發人員認證不支援 CAE。
令牌快取
令牌快取是 Azure 身分識別連結庫所提供的功能，可讓應用程式：
- 在記憶體中快取令牌 （預設值） 和磁碟上 （選擇加入）。
- 改善復原能力和效能。
- 減少對Microsoft Entra ID 提出的要求數目，以取得存取令牌。
Azure 身分識別連結庫同時提供記憶體內部和永續性磁碟快取。 如需詳細資訊，請參閱 令牌快取檔。
代理驗證
驗證代理程式是在使用者的計算機上執行，並管理連線帳戶的驗證交握和令牌維護。 目前僅支援 Windows Web 帳戶管理員 （WAM）。 若要啟用支援，請使用 @azure/identity-broker 套件。 如需使用 WAM 進行驗證的詳細資訊，請參閱 Broker 外掛程式檔。
故障排除
如需疑難解答的協助，請參閱 疑難解答指南。
後續步驟
閱讀檔
如需此連結庫的 API 檔，請參閱 檔案網站。
用戶端連結庫支援
Azure SDK 版本頁面上所列的用戶端和管理連結庫， 支援 Microsoft Entra 驗證接受來自此連結庫的認證。 深入瞭解如何在其檔中使用這些連結庫，這會從版本頁面連結。
已知問題
Azure AD B2C 支援
此連結庫不支援 azure AD B2C 服務
如需其他開啟的問題，請參閱連結庫的 GitHub 存放庫。
提供意見反應
貢獻
如果您想要參與此連結庫，請閱讀 參與指南，以深入瞭解如何建置和測試程序代碼。
