共用方式為

適用於 JavaScript 的 Azure 身分識別用戶端連結庫 - 4.5.0 版

  • 發行項

Azure 身分識別連結庫透過一組方便的 TokenCredential 實作，提供 Microsoft Entra ID （先前稱為 Azure Active Directory） 令牌驗證。

如需各種認證的範例，請參閱 Azure 身分識別範例頁面。

主要連結：

開始

目前支持的環境

  • LTS 版本的 Node.js
  • 最新版的 Safari、Chrome、Edge 和 Firefox。
    • 注意：在此連結庫中導出的不同認證中，InteractiveBrowserCredential 是瀏覽器中唯一支持的認證。

如需詳細資訊，請參閱我們的 支持原則。

安裝套件

使用 npm安裝 Azure 身分識別：

npm install --save @azure/identity

先決條件

@azure/identity 的使用時機

@azure/identity 公開的認證類別著重於提供最直接的方式，在本機、開發環境和生產環境中驗證 Azure SDK 用戶端。 我們的目標是簡化和合理的驗證通訊協議支援，以涵蓋 Azure 上可能的大部分驗證案例。 我們正積極擴充以涵蓋更多案例。 如需所提供的認證完整清單，請參閱 認證類別 一節。

Node.js支援 @azure/identity 提供的所有認證類型。 針對瀏覽器，InteractiveBrowserCredential 是用於基本身份驗證案例的認證類型。

@azure/identity 所提供的大部分認證類型都使用適用於 JavaScriptMSAL.js的 Microsoft 驗證連結庫。 具體而言，我們使用 v2 MSAL.js 連結庫，其會搭配 PKCE 使用 OAuth 2.0 授權碼流程，並且 符合 OpenID 規範。 雖然 @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未涵蓋的驗證案例。 若要深入瞭解，請參閱 自定義認證。

雖然我們的認證類型支援許多進階案例，但開發人員可能想要直接使用 Microsoft Authentication Library for JavaScript （MSAL.js）。 請考慮在下列案例中使用 MSAL.js：

  • 想要完全控制驗證通訊協定及其設定的開發人員。
  • 我們的認證類型旨在與 Azure SDK 用戶端搭配使用，並搭配核心 HTTP 層處理的智慧型手機快取和令牌重新整理。 如果您發現自己必須直接使用 getToken，您可以受益於使用 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進行驗證，請執行 命令 。 對於使用預設網頁瀏覽器在系統上執行的使用者，Azure CLI 會啟動瀏覽器來驗證使用者。

Azure CLI 帳戶登入

對於沒有預設網頁瀏覽器的系統，az login 命令會使用裝置程式代碼驗證流程。 使用者也可以強制 Azure CLI 使用裝置程式代碼流程，而不是藉由指定 --use-device-code 自變數來啟動瀏覽器。

Azure CLI 帳戶裝置程式代碼登入

透過 Azure PowerShell 進行驗證

使用 AzurePowerShellCredential的應用程式，無論是直接還是透過 DefaultAzureCredential，都可以使用連線到 Azure PowerShell 的帳戶，在本機執行時驗證應用程式中的呼叫。

若要向 Azure PowerShell進行驗證，請執行 Cmdlet。 根據預設，如同 Azure CLI， Connect-AzAccount 會啟動預設網頁瀏覽器來驗證用戶帳戶。

Azure PowerShell 帳戶登入

如果會話中不支援互動式驗證，則 -UseDeviceAuthentication 自變數會強制 Cmdlet 改用裝置程式代碼驗證流程，類似於 Azure CLI 認證中的對應選項。

透過 Visual Studio Code 進行驗證

使用 Visual Studio Code 的開發人員可以使用 Azure 帳戶擴充功能 透過編輯器進行驗證。 接著，使用 VisualStudioCodeCredential 的應用程式可以在本機執行時，使用此帳戶來驗證其應用程式中的呼叫。

若要在 Visual Studio Code 中驗證，請確定已安裝 Azure 帳戶擴充功能。 安裝之後，開啟 命令選擇區，然後執行 Azure：登入 命令。

此外，請使用 @azure/identity-vscode 外掛程式套件。 此套件提供 VisualStudioCodeCredential 的相依性，並加以啟用。 請參閱 外掛程式。

已知問題， 不適用於 Azure 帳戶擴充功能， 0.9.11版本。 此問題的長期修正正在進行中。 同時，請考慮透過 Azure CLI驗證 。

在瀏覽器中驗證用戶端

為了在網頁瀏覽器中驗證 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 主控環境中所使用的認證與本機開發中使用的認證結合在一起，來簡化驗證，同時開發部署至 Azure 的應用程式。 如需詳細資訊，請參閱 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。

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
// 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 可讓用戶結合多個認證實例來定義自定義的認證鏈結。 此範例示範如何建立嘗試使用兩個不同設定之 ClientSecretCredential實例進行驗證的 ChainedTokenCredential，然後從 @azure/keyvault-keys驗證 KeyClient：

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";
// 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
const client = new KeyClient(vaultUrl, credentialChain);

受控識別支援

受控識別驗證 可透過下列 Azure 服務直接 DefaultAzureCredential 或 ManagedIdentityCredential 認證類別來支援：

如需如何使用受控識別進行驗證的範例，請參閱 範例。

雲端設定

認證預設為向 Azure 公用雲端的 Microsoft Entra 端點進行驗證。 若要存取其他雲端中的資源，例如 Azure Government 或私人雲端，請使用建構函式中的 authorityHost 自變數來設定認證。 AzureAuthorityHosts 列舉會定義已知雲端的授權單位。 針對美國政府雲端，您可以透過下列方式具現化認證：

import { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  },
);

除了指定 authorityHost 自變數，您也可以將 AZURE_AUTHORITY_HOST 環境變數設定為雲端授權單位的 URL。 將多個認證設定為向相同雲端進行驗證，或當已部署的環境需要定義目標雲端時，此方法很有用：

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

AzureAuthorityHosts 列舉會為您的便利性定義已知雲端的授權單位：不過，如果雲端的授權單位未列在 AzureAuthorityHosts中，您可以傳遞任何有效的授權單位 URL 作為字串自變數。 例如：

import { ClientSecretCredential } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: "https://login.partner.microsoftonline.cn",
  },
);

並非所有認證都需要此設定。 透過開發工具進行驗證的認證，例如 AzureCliCredential，請使用此工具的組態。 同樣地，VisualStudioCodeCredential 接受 authorityHost 自變數，但預設為符合 Visual Studio Code Azure 的 authorityHost：雲端 設定。

認證類別

認證鏈

憑據 用法 例
DefaultAzureCredential 提供簡化的驗證體驗，以快速開始在 Azure 中執行應用程式。 範例
ChainedTokenCredential 允許使用者定義組成多個認證的自訂驗證流程。 範例

驗證 Azure 裝載的應用程式

憑據 用法 例
EnvironmentCredential 透過環境變數中指定的認證資訊來驗證服務主體或使用者。 範例
ManagedIdentityCredential 驗證 Azure 資源的受控識別。 範例
WorkloadIdentityCredential 支援 Kubernetes 上的 Microsoft Entra Workload ID。 範例

驗證服務主體

憑據 用法 例 參考
AzurePipelinesCredential 支援 Azure Pipelines 上的 Microsoft Entra Workload ID。 範例
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_SEND_CERTIFICATE_CHAIN （選擇性） 在 x5c 標頭中傳送憑證鏈結以支援主體名稱/簽發者型驗證

用戶名稱和密碼

變數名稱 價值
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 存放庫。

提供意見反應

如果您遇到錯誤或有建議，開啟問題。

貢獻

若要參與此連結庫，請閱讀 參與指南，以深入瞭解如何建置和測試程序代碼。

印象