Verificatie met Microsoft Authentication Library (MSAL) in apps

  • Artikel

Als u programmatisch wilt verifiëren met uw cluster, moet u een toegangstoken aanvragen van Microsoft Entra id die specifiek is voor Azure Data Explorer. Dit toegangstoken fungeert als bewijs van identiteit bij het verzenden van aanvragen naar uw cluster. U kunt een van de MSAL-stromen (Microsoft Authentication Library) gebruiken om een toegangstoken te maken.

In dit artikel wordt uitgelegd hoe u MSAL gebruikt om principals te verifiëren bij uw cluster. Het directe gebruik van MSAL voor het verifiëren van principals is voornamelijk relevant in webtoepassingen waarvoor OBO-verificatie (On-behalf-of) of SPA-verificatie (Single Page Application) is vereist. Voor andere gevallen raden we u aan de Kusto-clientbibliotheken te gebruiken, omdat deze het verificatieproces vereenvoudigen.

In dit artikel vindt u meer informatie over de belangrijkste verificatiescenario's, de informatie die moet worden geboden voor een geslaagde verificatie en het gebruik van MSAL voor verificatie.

Verificatiescenario's

De belangrijkste verificatiescenario's zijn als volgt:

  • Gebruikersverificatie: wordt gebruikt om de identiteit van menselijke gebruikers te verifiëren.

  • Toepassingsverificatie: wordt gebruikt om de identiteit te verifiëren van een toepassing die toegang moet hebben tot resources zonder tussenkomst van een persoon met behulp van geconfigureerde referenties.

  • On-behalf-of -verificatie (OBO): hiermee kan een toepassing een token uitwisselen voor deze toepassing met een token voor toegang tot een Kusto-service. Deze stroom moet worden geïmplementeerd met MSAL.

  • Verificatie van toepassing met één pagina (SPA): hiermee kunnen webtoepassingen met beveiligd-WACHTWOORDVERIFICATIE aan clientzijde gebruikers aanmelden en tokens ophalen voor toegang tot uw cluster. Deze stroom moet worden geïmplementeerd met MSAL.

Voor gebruikers- en toepassingsverificatie raden we u aan de Kusto-clientbibliotheken te gebruiken. Voor OBO- en BEVEILIGD-WACHTWOORDVERIFICATIE-verificatie kunnen de Kusto-clientbibliotheken niet worden gebruikt.

Verificatieparameters

Tijdens het ophalen van het token moet de client de volgende parameters opgeven:

Parameternaam Beschrijving
Resource-id De resource-id waarvoor het Microsoft Entra toegangstoken moet worden uitgeven. De resource-id is de cluster-URI zonder poortgegevens en pad.

Voorbeeld: de resource-id voor het help cluster is https://help.kusto.windows.net.
tenant-id van Microsoft Entra Microsoft Entra-id is een multitenant-service en elke organisatie kan een object maken dat een map wordt genoemd met beveiligingsgerelateerde objecten, zoals gebruikersaccounts en toepassingen. Microsoft Entra-id verwijst vaak naar de map als een tenant. Elke tenant heeft een tenant-id in de vorm van een GUID. In veel gevallen kan de domeinnaam van de organisatie ook worden gebruikt om de Microsoft Entra tenant te identificeren.

Voorbeeld: Een organisatie 'Contoso' kan de tenant-id 12345678-a123-4567-b890-123a456b789c en de domeinnaam contoso.comhebben.
Microsoft Entra instantie-URI Het eindpunt dat wordt gebruikt voor verificatie. De Microsoft Entra directory of tenant bepaalt de Microsoft Entra instantie-URI. De URI is https://login.microsoftonline.com/{tenantId} waar {tenantId} de tenant-id of domeinnaam is.

Voorbeeld: bijvoorbeeld https://login.microsoftonline.com/12345678-a123-4567-b890-123a456b789c.

Notitie

Het Microsoft Entra service-eindpunt verandert in nationale clouds. Wanneer u werkt met een Azure Data Explorer-service die is geïmplementeerd in een nationale cloud, stelt u het bijbehorende service-eindpunt voor de nationale cloud in Microsoft Entra.

Gebruikersverificatie uitvoeren met MSAL

In het volgende codevoorbeeld ziet u hoe u MSAL gebruikt om een autorisatietoken voor uw cluster op te halen. De autorisatie wordt uitgevoerd op een manier die de interactieve aanmeldingsgebruikersinterface start. De appRedirectUri is de URL waarnaar Microsoft Entra-id wordt omgeleid nadat de verificatie is voltooid. MSAL extraheert de autorisatiecode uit deze omleiding.

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

Notitie

  • U wordt aangeraden waar mogelijk de Kusto-clientbibliotheken te gebruiken. Deze bibliotheken vereenvoudigen het verificatieproces doordat u verificatie-eigenschappen kunt opgeven in de Kusto-verbindingsreeks.
  • Met de Kusto-clientbibliotheken worden Microsoft Entra tokens opgeslagen in een lokale tokencache op de computer van de gebruiker om het aantal keren dat ze om referenties worden gevraagd te verminderen. Het cachebestand is %APPDATA%\Kusto\userTokenCache.data en kan alleen worden geopend door de aangemelde gebruiker.

Toepassingsverificatie uitvoeren met MSAL

In het volgende codevoorbeeld ziet u hoe u MSAL gebruikt om een autorisatietoken voor uw cluster op te halen. In deze stroom wordt geen prompt weergegeven. De toepassing moet zijn geregistreerd met Microsoft Entra-id en een app-sleutel of een X509v2-certificaat hebben dat is uitgegeven door Microsoft Entra-id. Zie Een Microsoft Entra-toepassing inrichten als u een toepassing wilt instellen.

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

Notitie

U wordt aangeraden waar mogelijk de Kusto-clientbibliotheken te gebruiken. Deze bibliotheken vereenvoudigen het verificatieproces doordat u verificatie-eigenschappen kunt opgeven in de Kusto-verbindingsreeks.

OBO-verificatie (On-behalf-of) uitvoeren

On-behalf-of-verificatie is relevant wanneer uw webtoepassing of -service fungeert als een bemiddelaar tussen de gebruiker of toepassing en uw cluster.

In dit scenario wordt aan een toepassing een Microsoft Entra toegangstoken voor een willekeurige resource verzonden. Vervolgens gebruikt de toepassing dat token om een nieuw Microsoft Entra toegangstoken te verkrijgen voor de Azure Data Explorer-resource. Vervolgens heeft de toepassing toegang tot uw cluster namens de principal die wordt aangegeven door het oorspronkelijke Microsoft Entra toegangstoken. Deze stroom wordt de OAuth 2.0 on-behalf-of-verificatiestroom genoemd. Het vereist over het algemeen meerdere configuratiestappen met Microsoft Entra-id en in sommige gevallen is speciale toestemming van de beheerder van de Microsoft Entra-tenant vereist.

Ga als volgende te werk om namens verificatie uit te voeren:

  1. Een Microsoft Entra-toepassing inrichten.

  2. Stel een vertrouwensrelatie tot stand tussen de toepassing en uw cluster. Volg hiervoor de stappen in Gedelegeerde machtigingen configureren.

  3. Gebruik MSAL in de servercode om de tokenuitwisseling uit te voeren.

    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. Gebruik het token om query's uit te voeren. Bijvoorbeeld:

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

Verificatie van toepassing met één pagina (SPA) uitvoeren

Voor verificatie voor een beveiligd-WACHTWOORDVERIFICATIE-webclient gebruikt u de OAuth-autorisatiecodestroom.

In dit scenario wordt de app omgeleid om zich aan te melden bij Microsoft Entra-id. Vervolgens wordt Microsoft Entra-id teruggeleid naar de app met een autorisatiecode in de URI. Vervolgens verzendt de app een aanvraag naar het tokeneindpunt om het toegangstoken op te halen. Het token is 24 uur geldig gedurende welke de client het opnieuw kan gebruiken door het token op de achtergrond te verkrijgen.

Microsoft identity platform bevat gedetailleerde zelfstudies voor verschillende gebruiksvoorbeelden, zoals React, Angular en JavaScript.

Verificatie instellen voor een webclient:

  1. Een Microsoft Entra-toepassing inrichten.

  2. Configureer de app zoals beschreven in MSAL.js 2.0 met verificatiecodestroom.

  3. Gebruik de MSAL.js 2.0-bibliotheek om een gebruiker aan te melden en te verifiëren bij uw cluster. Microsoft identity platform bevat gedetailleerde zelfstudies voor verschillende gebruiksvoorbeelden, zoals React, Angular en JavaScript.

    In het volgende voorbeeld wordt de MSAL.js-bibliotheek gebruikt voor toegang tot 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];

Gerelateerde inhoud