共用方式為

用於代理驗證的 Azure 身分識別外掛程式

  • 發行項

此套件提供適用於 JavaScript 的 Azure 身分識別連結庫外掛程式（@azure/identity），以使用驗證代理程式，例如 WAM。

驗證代理人是在使用者計算機上執行的應用程式，可管理連線帳戶的驗證交握和令牌維護。 目前僅支援 Windows 驗證代理程式 Web 帳戶管理員 （WAM）。

原始程式碼 | 範例 | API 參考文件 |[Microsoft Entra ID 檔]（https://learn.microsoft.com/entra/identity/）

開始

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

先決條件

安裝套件

此套件的設計目的是要與適用於 JavaScript 的 Azure 身分識別搭配使用。 使用 npm安裝 @azure/identity 與此套件：

npm install --save @azure/identity
npm install --save @azure/identity-broker

支援的環境

從 v18 開始，適用於 JavaScript 的 Azure 身分識別外掛程式支援穩定（偶數編號）Node.js 版本。 雖然外掛程式可以在其他 Node.js 版本中執行，但不保證支援。 @azure/identity-broker 不支援瀏覽器環境。

重要概念

如果這是您第一次使用 @azure/identity 或 Microsoft Entra 標識符，建議您先閱讀 使用 @azure/identity 搭配 Microsoft Entra ID。 本檔可讓您更深入了解平臺，以及如何正確設定您的 Azure 帳戶。

父視窗句柄

透過 InteractiveBrowserCredential向訊息代理程式進行驗證時，必須有父視窗句柄，以確保在要求視窗上正確顯示驗證對話方塊。 在裝置上圖形使用者介面的內容中，視窗句柄是操作系統指派給每個視窗的唯一標識符。 對於 Windows 作業系統，此句柄是整數值，可作為特定窗口的參考。

Microsoft帳戶 （MSA） 傳遞

Microsoft帳戶 （MSA） 是由使用者建立來存取Microsoft服務的個人帳戶。 MSA 傳遞是舊版設定，可讓使用者取得通常不接受 MSA 登入的資源令牌。 此功能僅適用於第一方應用程式。 使用設定為使用 MSA 傳遞的應用程式進行驗證的使用者可以將 legacyEnableMsaPassthrough 設定為 true 內部 InteractiveBrowserCredentialNodeOptions.brokerOptions，以允許 WAM 列出這些個人帳戶。

重新導向URI

Microsoft Entra 應用程式依賴重新導向 URI 來判斷在使用者登入之後傳送驗證回應的位置。 若要透過WAM啟用代理驗證，應該向應用程式註冊符合下列模式的重新導向 URI：

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Azure 身分識別外掛程式

自 @azure/identity 2.0.0 版起，適用於 JavaScript 的身分識別客戶端連結庫包含外掛程式 API。 此套件 （@azure/identity-broker） 會匯出外掛程式物件，您必須從 @azure/identity 套件將自變數當做自變數傳遞至最上層 useIdentityPlugin 函式。 在您的程式中啟用原生訊息代理程式，如下所示：

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

呼叫 useIdentityPlugin之後，原生訊息代理程式外掛程式會註冊至 @azure/identity 套件，且可在支援 WAM 訊息代理程式驗證的 InteractiveBrowserCredential 上使用。 此認證在建構函式選項中 brokerOptions。

例子

註冊外掛程式之後，您可以傳遞 brokerOptions，並將 enabled 屬性設定為 true 至認證建構函式，以啟用WAM訊息代理程序驗證。 在下列範例中，我們使用 InteractiveBrowserCredential。

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");

如需使用電子應用程式擷取視窗句柄的完整範例，請參閱此範例。

使用預設帳戶進行登入

當 [useDefaultBrokerAccount] 選項設定為 true時，認證會嘗試以無訊息方式使用預設的訊息代理程序帳戶。 如果使用預設帳戶失敗，認證將會回復為互動式驗證。

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    useDefaultBrokerAccount: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");

故障排除

如需如何診斷各種失敗案例的詳細資訊，請參閱 Azure 身分識別 [疑難解答指南][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md]。

伐木

啟用記錄可能有助於找出有關失敗的實用資訊。 若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在運行時間啟用記錄，方法是在 setLogLevel中呼叫 @azure/logger：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

後續步驟

提供意見反應

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

貢獻

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

印象