Sdílet prostřednictvím

Ověřování pomocí knihovny Microsoft Authentication Library (MSAL) v aplikacích

  • Článek

Pokud chcete pomocí kódu programu ověřit cluster, musíte požádat o přístupový token z Microsoft Entra ID specifického pro Azure Data Explorer. Tento přístupový token funguje jako důkaz identity při vystavování požadavků na váš cluster. K vytvoření přístupového tokenu můžete použít jeden z tokůknihovny MSAL (Microsoft Authentication Library).

Tento článek vysvětluje, jak pomocí knihovny MSAL ověřovat objekty zabezpečení ve vašem clusteru. Přímé použití knihovny MSAL k ověřování objektů zabezpečení je relevantní především ve webových aplikacích, které vyžadují ověřování on-behalf-of (OBO) nebo jednostránkovou aplikaci (SPA). V jiných případech doporučujeme používat klientské knihovny Kusto , které zjednodušují proces ověřování.

V tomto článku se seznámíte s hlavními scénáři ověřování, informacemi, které se mají poskytnout pro úspěšné ověřování, a použitím msal pro ověřování.

Scénáře ověřování

Hlavní scénáře ověřování jsou následující:

  • Ověřování uživatelů: Používá se k ověření identity lidských uživatelů.

  • Ověřování aplikací: Používá se k ověření identity aplikace, která potřebuje přistupovat k prostředkům bez zásahu člověka pomocí nakonfigurovaných přihlašovacích údajů.

  • Ověřování on-behalf-of (OBO): Umožňuje aplikaci vyměnit token za určitou aplikaci s tokenem pro přístup ke službě Kusto. Tento tok musí být implementovaný s MSAL.

  • Ověřování jednostránkovou aplikací (SPA): Umožňuje webovým aplikacím SPA na straně klienta přihlásit uživatele a získat tokeny pro přístup ke clusteru. Tento tok musí být implementovaný s MSAL.

Pro ověřování uživatelů a aplikací doporučujeme používat klientské knihovny Kusto. Pro ověřování OBO a SPA není možné použít klientské knihovny Kusto.

Parametry ověřování

Během procesu získávání tokenů musí klient zadat následující parametry:

Název parametru Description
ID prostředku ID prostředku, pro který se má vydat přístupový token Microsoft Entra. ID prostředku je identifikátor URI clusteru bez informací o portu a cesty.

Příklad: ID prostředku clusteru help je https://help.kusto.windows.net.
ID tenanta Microsoft Entra Microsoft Entra ID je služba s více tenanty a každá organizace může vytvořit objekt s názvem adresář, který obsahuje objekty související se zabezpečením, jako jsou uživatelské účty a aplikace. Microsoft Entra ID často označuje adresář jako tenanta. Každý tenant má ID tenanta ve formě identifikátoru GUID. V mnoha případech je možné k identitě tenanta Microsoft Entra použít také název domény organizace.

Příklad: Organizace Contoso může mít ID 12345678-a123-4567-b890-123a456b789c tenanta a název contoso.comdomény .
identifikátor URI autority Microsoft Entra Koncový bod, který se používá k ověřování. Adresář Microsoft Entra neboli tenant určuje identifikátor URI autority Microsoft Entra. Identifikátor URI je https://login.microsoftonline.com/{tenantId} místo, kde {tenantId} je buď ID tenanta, nebo název domény.

Příklad: Například https://login.microsoftonline.com/12345678-a123-4567-b890-123a456b789c.

Poznámka

Koncový bod služby Microsoft Entra se mění v národních cloudech. Při práci se službou Azure Data Explorer nasazenou v národním cloudu nastavte odpovídající koncový bod služby Microsoft Entra národního cloudu.

Ověřování uživatelů pomocí MSAL

Následující ukázka kódu ukazuje, jak pomocí knihovny MSAL získat autorizační token pro váš cluster. Autorizace se provádí způsobem, který spustí uživatelské rozhraní interaktivního přihlašování. Je appRedirectUri adresa URL, na kterou Microsoft Entra ID přesměruje po úspěšném dokončení ověřování. MSAL extrahuje autorizační kód z tohoto přesměrování.

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));

Poznámka

  • Kdykoli je to možné, doporučujeme používat klientské knihovny Kusto . Tyto knihovny zjednodušují proces ověřování tím, že umožňují zadat vlastnosti ověřování v připojovací řetězec Kusto.
  • V klientských knihovnách Kusto se tokeny Microsoft Entra ukládají do místní mezipaměti tokenů na počítači uživatele, aby se snížil počet zobrazení výzvy k zadání přihlašovacích údajů. Soubor mezipaměti je %APPDATA%\Kusto\userTokenCache.data a má přístup jenom přihlášený uživatel.

Ověřování aplikací pomocí MSAL

Následující ukázka kódu ukazuje, jak pomocí knihovny MSAL získat autorizační token pro váš cluster. V tomto toku se nezobrazí žádná výzva. Aplikace musí být zaregistrovaná s ID Microsoft Entra a musí mít klíč aplikace nebo certifikát X509v2 vydaný Microsoft Entra ID. Informace o nastavení aplikace najdete v tématu Zřízení aplikace 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));

Poznámka

Kdykoli je to možné, doporučujeme používat klientské knihovny Kusto . Tyto knihovny zjednodušují proces ověřování tím, že umožňují zadat vlastnosti ověřování v připojovací řetězec Kusto.

Provedení ověřování jménem uživatele (OBO)

Ověřování jménem je relevantní, pokud webová aplikace nebo služba funguje jako zprostředkovatel mezi uživatelem nebo aplikací a vaším clusterem.

V tomto scénáři se aplikaci odešle Microsoft Entra přístupový token pro libovolný prostředek. Aplikace pak tento token použije k získání nového přístupového tokenu Microsoft Entra pro prostředek Azure Data Explorer. Aplikace pak bude mít přístup ke clusteru jménem objektu zabezpečení označeného původním přístupovým tokenem Microsoft Entra. Tento tok se nazývá tok ověřování OAuth 2.0 on-behalf-of. Obecně vyžaduje několik kroků konfigurace s ID Microsoft Entra a v některých případech může vyžadovat zvláštní souhlas správce tenanta Microsoft Entra.

Postup provedení ověřování jménem uživatele:

  1. Zřiďte Microsoft Entra aplikaci.

  2. Vytvořte vztah důvěryhodnosti mezi aplikací a vaším clusterem. Postupujte podle pokynů v tématu Konfigurace delegovaných oprávnění.

  3. V kódu serveru použijte msal k provedení výměny tokenů.

    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;

  4. Ke spouštění dotazů použijte token. Příklad:

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

Ověřování jednostránkové aplikace (SPA)

Pro ověřování webového klienta SPA použijte tok autorizačního kódu OAuth.

V tomto scénáři se aplikace přesměruje, aby se přihlásila k Microsoft Entra ID. Pak Microsoft Entra ID přesměruje zpět do aplikace s autorizačním kódem v identifikátoru URI. Pak aplikace odešle žádost koncovému bodu tokenu o získání přístupového tokenu. Token je platný po dobu 24 hodin, během kterých ho klient může znovu použít získáním tokenu bezobslužně.

Microsoft identity platform obsahuje podrobné kurzy pro různé případy použití, jako jsou React, Angular a JavaScript.

Nastavení ověřování pro webového klienta:

  1. Zřiďte Microsoft Entra aplikaci.

  2. Nakonfigurujte aplikaci podle popisu v MSAL.js 2.0 s tokem kódu ověřování.

  3. Pomocí knihovny MSAL.js 2.0 se můžete přihlásit k uživateli a ověřit se ve vašem clusteru. Microsoft identity platform obsahuje podrobné kurzy pro různé případy použití, jako jsou React, Angular a JavaScript.

    Následující příklad používá knihovnu MSAL.js pro přístup k Azure Data Explorer.

    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];

Související obsah