如何在應用程式中使用 Microsoft 驗證連結庫進行驗證

發行項
10/30/2024

適用於： ✅Microsoft網狀架構✅Azure 數據總管

若要以程式設計方式向叢集進行驗證，您必須向 Azure 數據總管特定的Microsoft Entra 識別元要求存取令牌。此存取令牌可作為向叢集發出要求時的身分識別證明。您可以使用其中一個 Microsoft驗證連結庫（MSAL）流程來建立存取令牌。

本文說明如何使用 MSAL 來驗證叢集的主體。直接使用 MSAL 來驗證主體主要與需要代理者（OBO）驗證或單頁應用程式（SPA）驗證的 Web 應用程式相關。針對其他情況，建議您在簡化驗證程式時使用 Kusto 用戶端連結庫。

在本文中，瞭解主要驗證案例、提供成功驗證的資訊，以及使用 MSAL 進行驗證。

驗證案例

主要驗證案例如下：

用戶驗證：用來驗證人類使用者的身分識別。
應用程式驗證：用來驗證需要存取資源的應用程式身分識別，而不需使用已設定的認證進行人為介入。
代表（OBO）驗證：允許應用程式使用令牌來交換令牌給上述應用程式，以存取 Kusto 服務。此流程必須使用 MSAL 實作。
單頁應用程式（SPA）驗證：允許用戶端 SPA Web 應用程式登入使用者，並取得令牌來存取您的叢集。此流程必須使用 MSAL 實作。

針對使用者和應用程式驗證，我們建議使用 Kusto 用戶端連結庫。針對 OBO 和 SPA 驗證，無法使用 Kusto 用戶端連結庫。

Authentication parameters

在令牌擷取程式期間，客戶端必須提供下列參數：

參數名稱	描述
資源識別碼	要發行Microsoft Entra 存取令牌的資源標識碼。資源標識碼是沒有埠資訊和路徑的叢集 URI。範例：叢集的資源識別碼 `help` 為 `https://help.kusto.windows.net`。
Microsoft Entra 租用戶識別碼	Microsoft Entra ID 是多租用戶服務，而且每個組織都可以建立稱為目錄的物件，該目錄會保存安全性相關物件，例如使用者帳戶和應用程式。 Microsoft Entra ID 通常會將目錄稱為租用戶。每個租使用者都有 GUID 形式的租用戶標識碼。在許多情況下，組織功能變數名稱也可以用來識別Microsoft Entra 租使用者。範例：組織「Contoso」可能有租使用者識別碼 `aaaabbbb-0000-cccc-1111-dddd2222eeee` 和功能變數名稱 `contoso.com`。
Microsoft Entra 授權單位 URI	用於驗證的端點。 Microsoft Entra 目錄或租用戶會決定Microsoft Entra 授權單位 URI。 URI 是`https://login.microsoftonline.com/{tenantId}`租用戶標識碼或功能變數名稱。`{tenantId}` 範例：例如。 `https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee`

注意

國家雲端中的 Microsoft Entra 服務端點會變更。使用部署於國家雲端的 Azure 數據總管服務時，請設定對應的國家雲端Microsoft Entra 服務端點。

使用 MSAL 執行使用者驗證

下列程式代碼範例示範如何使用 MSAL 來取得叢集的授權令牌。授權是以啟動互動式登入UI的方式完成。 appRedirectUri是驗證成功完成之後，Microsoft Entra ID 重新導向的URL。 MSAL 會從這個重新導向擷取授權碼。

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";

var authClient = PublicClientApplicationBuilder.Create("<appId>")
    .WithAuthority($"https://login.microsoftonline.com/<appTenant>")
    .WithRedirectUri("<appRedirectUri>")
    .Build();

var result = authClient.AcquireTokenInteractive(
    new[] { $"{kustoUri}/.default" } // Define scopes for accessing Azure Data Explorer cluster
).ExecuteAsync().Result;

var bearerToken = result.AccessToken;

var request = WebRequest.Create(new Uri(kustoUri));
request.Headers.Set(HttpRequestHeader.Authorization, string.Format(CultureInfo.InvariantCulture, "{0} {1}", "Bearer", bearerToken));

注意

建議您盡可能使用 Kusto 用戶端連結庫。這些連結庫可讓您在 Kusto 連接字串中提供驗證屬性，以簡化驗證程式。
使用 Kusto 用戶端連結庫時，Microsoft Entra 令牌會儲存在用戶電腦上的本機令牌快取中，以減少提示輸入認證的次數。快取檔案是 %APPDATA%\Kusto\userTokenCache.data ，只能由登入的使用者存取。

使用 MSAL 執行應用程式驗證

下列程式代碼範例示範如何使用 MSAL 來取得叢集的授權令牌。在此流程中，不會顯示任何提示。應用程式必須向 Microsoft Entra ID 註冊，並具有應用程式密鑰或 Microsoft Entra ID 所簽發的 X509v2 憑證。若要設定應用程式，請參閱布建Microsoft Entra 應用程式。

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";

var authClient = ConfidentialClientApplicationBuilder.Create("<appId>")
    .WithAuthority($"https://login.microsoftonline.com/<appTenant>")
    .WithClientSecret("<appKey>") // Can be replaced by .WithCertificate to authenticate with an X.509 certificate
    .Build();

var result = authClient.AcquireTokenForClient(
    new[] { $"{kustoUri}/.default" } // Define scopes for accessing Azure Data Explorer cluster
).ExecuteAsync().Result;
var bearerToken = result.AccessToken;

var request = WebRequest.Create(new Uri(kustoUri));
request.Headers.Set(HttpRequestHeader.Authorization, string.Format(CultureInfo.InvariantCulture, "{0} {1}", "Bearer", bearerToken));

注意

建議您盡可能使用 Kusto 用戶端連結庫。這些連結庫可讓您在 Kusto 連接字串中提供驗證屬性，以簡化驗證程式。

執行代理者（OBO）驗證

當您的 Web 應用程式或服務作為使用者或應用程式與叢集之間的調解器時，代表驗證是相關的。

在此案例中，應用程式會針對任意資源傳送Microsoft Entra 存取令牌。然後，應用程式會使用該令牌來取得 Azure 數據總管資源的新Microsoft Entra 存取令牌。然後，應用程式可以代表原始Microsoft Entra 存取令牌所指示的主體存取叢集。此流程稱為 OAuth 2.0 代理驗證流程。它通常需要具有Microsoft Entra標識符的多個組態步驟，在某些情況下，可能需要Microsoft Entra 租用戶的系統管理員進行特殊同意。

若要執行代理驗證：

布建Microsoft Entra 應用程式。
建立應用程式與叢集之間的信任關係。若要這樣做，請遵循設定委派許可權中的步驟。

在您的伺服器程式代碼中，使用 MSAL 來執行令牌交換。

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";

var authClient = ConfidentialClientApplicationBuilder.Create("<appId>")
    .WithAuthority($"https://login.microsoftonline.com/<appTenant>")
    .WithClientSecret("<appKey>") // Can be replaced by .WithCertificate to authenticate with an X.509 certificate
    .Build();

var result = authClient.AcquireTokenOnBehalfOf(
    new[] { $"{kustoUri}/.default" }, // Define scopes for accessing your cluster
    new UserAssertion("<userAccessToken>") // Encode the "original" token that will be used for exchange
).ExecuteAsync().Result;
var accessTokenForAdx = result.AccessToken;

使用令牌來執行查詢。例如：

var request = WebRequest.Create(new Uri(kustoUri));
request.Headers.Set(HttpRequestHeader.Authorization, string.Format(CultureInfo.InvariantCulture, "{0} {1}", "Bearer", accessTokenForAdx));

執行單頁應用程式（SPA）驗證

若要驗證 SPA Web 用戶端，請使用 OAuth 授權碼流程。

在此案例中，應用程式會重新導向至登入 Microsoft Entra ID。然後，Microsoft Entra ID 會以 URI 中的授權碼重新導向回應用程式。然後，應用程式會向令牌端點提出要求，以取得存取令牌。令牌的有效期限為 24 小時，用戶端可以透過以無訊息方式取得令牌來重複使用令牌。

Microsoft 身分識別平台具有不同使用案例的詳細教學課程，例如React、Angular 和 JavaScript。

若要設定 Web 客戶端的驗證：

布建Microsoft Entra 應用程式。
使用驗證碼流程設定應用程式，如 MSAL.js 2.0 中所述。

使用 MSAL.js 2.0 連結庫來登入使用者，並驗證您的叢集。 Microsoft 身分識別平台針對不同使用案例的詳細教學課程，例如React、Angular 和 JavaScript。

下列範例會使用 MSAL.js 連結庫來存取 Azure 數據總管。

import * as msal from "@azure/msal-browser";

const msalConfig = {
  auth: {
    clientId: "<AAD client application ID>",
    authority: "https://login.microsoftonline.com/<AAD tenant ID>",
  },
};

const msalInstance = new msal.PublicClientApplication(msalConfig);
const myAccounts = msalInstance.getAllAccounts();

// If no account is logged in, redirect the user to log in.
if (myAccounts === undefined || myAccounts.length === 0) {
  try {
    await msalInstance.loginRedirect({
      scopes: ["https://help.kusto.windows.net/.default"],
    });
  } catch (err) {
    console.error(err);
  }
}
const account = myAccounts[0];
const name = account.name;
window.document.getElementById("main").innerHTML = `Hi ${name}!`;

// Get the access token required to access the specified Azure Data Explorer cluster.
const accessTokenRequest = {
  account,
  scopes: ["https://help.kusto.windows.net/.default"],
};
let acquireTokenResult = undefined;
try {
  acquireTokenResult = await msalInstance.acquireTokenSilent(accessTokenRequest);
} catch (error) {
  if (error instanceof InteractionRequiredAuthError) {
    await msalInstance.acquireTokenRedirect(accessTokenRequest);
  }
}

const accessToken = acquireTokenResult.accessToken;

// Make requests to the specified cluster with the token in the Authorization header.
const fetchResult = await fetch("https://help.kusto.windows.net/v2/rest/query", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    db: "Samples",
    csl: "StormEvents | count",
  }),
});
const jsonResult = await fetchResult.json();

// The following line extracts the first cell in the result data.
const count = jsonResult.filter((x) => x.TableKind === "PrimaryResult")[0].Rows[0][0];

共用方式為

如何在應用程式中使用 Microsoft 驗證連結庫進行驗證

驗證案例

Authentication parameters

使用 MSAL 執行使用者驗證

使用 MSAL 執行應用程式驗證

執行代理者（OBO）驗證

執行單頁應用程式（SPA）驗證

意見反應

其他資源

共用方式為

如何在應用程式中使用 Microsoft 驗證連結庫進行驗證

驗證案例

Authentication parameters

使用 MSAL 執行使用者驗證

使用 MSAL 執行應用程式驗證

執行代理者 （OBO） 驗證

執行單頁應用程式 （SPA） 驗證

相關內容

意見反應

其他資源

執行代理者（OBO）驗證

執行單頁應用程式（SPA）驗證