Authentifizieren mit der Microsoft Authentication Library (MSAL) in Apps

  • Artikel

Für die programmgesteuerte Authentifizierung bei Ihrem Cluster müssen Sie ein Zugriffstoken von Microsoft Entra für Azure Data Explorer spezifische ID anfordern. Dieses Zugriffstoken dient als Identitätsnachweis, wenn Anforderungen an Ihren Cluster ausgegeben werden. Sie können einen der MSAL-Flows (Microsoft Authentication Library) verwenden, um ein Zugriffstoken zu erstellen.

In diesem Artikel wird erläutert, wie Sie MSAL verwenden, um Prinzipale bei Ihrem Cluster zu authentifizieren. Die direkte Verwendung von MSAL zur Authentifizierung von Prinzipalen ist in erster Linie in Webanwendungen relevant, die eine Authentifizierung im Auftrag von (OBO) oder eine Authentifizierung mit Single Page Application (SPA) erfordern. In anderen Fällen wird empfohlen, die Kusto-Clientbibliotheken zu verwenden, um den Authentifizierungsprozess zu vereinfachen.

In diesem Artikel erfahren Sie mehr über die Standard Authentifizierungsszenarien, die Informationen, die für eine erfolgreiche Authentifizierung bereitgestellt werden müssen, und die Verwendung von MSAL für die Authentifizierung.

Authentifizierungsszenarien

Die Standard Authentifizierungsszenarien sind wie folgt:

  • Benutzerauthentifizierung: Wird verwendet, um die Identität von menschlichen Benutzern zu überprüfen.

  • Anwendungsauthentifizierung: Wird verwendet, um die Identität einer Anwendung zu überprüfen, die ohne menschliches Eingreifen mithilfe konfigurierter Anmeldeinformationen auf Ressourcen zugreifen muss.

  • Authentifizierung im Auftrag von (OBO): Ermöglicht es einer Anwendung, ein Token für diese Anwendung mit einem Token auszutauschen, um auf einen Kusto-Dienst zuzugreifen. Dieser Flow muss mit MSAL implementiert werden.

  • Single Page Application (SPA)-Authentifizierung: Ermöglicht clientseitigen SPA-Webanwendungen die Anmeldung von Benutzern und das Abrufen von Token für den Zugriff auf Ihren Cluster. Dieser Flow muss mit MSAL implementiert werden.

Für die Benutzer- und Anwendungsauthentifizierung empfehlen wir die Verwendung der Kusto-Clientbibliotheken. Für die OBO- und SPA-Authentifizierung können die Kusto-Clientbibliotheken nicht verwendet werden.

Authentifizierungsparameter

Während des Tokenakquisitionsprozesses muss der Client die folgenden Parameter bereitstellen:

Parametername BESCHREIBUNG
Ressourcen-ID Die Ressourcen-ID, für die das Microsoft Entra-Zugriffstokens ausstellen soll. Die Ressourcen-ID ist der Cluster-URI ohne Portinformationen und Pfad.

Beispiel: Die Ressourcen-ID für den help Cluster ist https://help.kusto.windows.net.
Microsoft Entra Mandanten-ID Microsoft Entra ID ist ein mehrinstanzenfähiger Dienst, und jeder organization kann ein Objekt namens Verzeichnis erstellen, das sicherheitsbezogene Objekte wie Benutzerkonten und Anwendungen enthält. Microsoft Entra ID bezieht sich häufig auf das Verzeichnis als Mandanten. Jeder Mandant verfügt über eine Mandanten-ID in Form einer GUID. In vielen Fällen kann auch der Domänenname des organization verwendet werden, um den Microsoft Entra Mandanten zu identifizieren.

Beispiel: Ein organization "Contoso" kann die Mandanten-ID 12345678-a123-4567-b890-123a456b789c und den Domänennamen contoso.comaufweisen.
Microsoft Entra Autoritäts-URI Der für die Authentifizierung verwendete Endpunkt. Das Microsoft Entra Verzeichnis oder Mandant bestimmt den Microsoft Entra Autoritäts-URI. Der URI ist https://login.microsoftonline.com/{tenantId} entweder {tenantId} die Mandanten-ID oder der Domänenname.

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

Hinweis

Der Microsoft Entra-Dienstendpunkt ändert sich in nationalen Clouds. Wenn Sie mit einem Azure Data Explorer-Dienst arbeiten, der in einer nationalen Cloud bereitgestellt wird, legen Sie den entsprechenden nationalen Cloud-Microsoft Entra-Dienstendpunkt fest.

Durchführen der Benutzerauthentifizierung mit MSAL

Das folgende Codebeispiel zeigt, wie Sie MSAL verwenden, um ein Autorisierungstoken für Ihren Cluster abzurufen. Die Autorisierung erfolgt so, dass die interaktive Anmeldebenutzeroberfläche gestartet wird. Dies appRedirectUri ist die URL, an die Microsoft Entra-ID weitergeleitet wird, nachdem die Authentifizierung erfolgreich abgeschlossen wurde. MSAL extrahiert den Autorisierungscode aus dieser Umleitung.

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

Hinweis

  • Es wird empfohlen, nach Möglichkeit die Kusto-Clientbibliotheken zu verwenden. Diese Bibliotheken vereinfachen den Authentifizierungsprozess, indem Sie Authentifizierungseigenschaften im Kusto-Verbindungszeichenfolge bereitstellen können.
  • Bei den Kusto-Clientbibliotheken werden Microsoft Entra Token in einem lokalen Tokencache auf dem Computer des Benutzers gespeichert, um die Anzahl der Aufforderungen zur Eingabe von Anmeldeinformationen zu verringern. Die Cachedatei lautet %APPDATA%\Kusto\userTokenCache.data und kann nur vom angemeldeten Benutzer zugegriffen werden.

Durchführen der Anwendungsauthentifizierung mit MSAL

Das folgende Codebeispiel zeigt, wie Sie MSAL verwenden, um ein Autorisierungstoken für Ihren Cluster abzurufen. In diesem Flow wird keine Eingabeaufforderung angezeigt. Die Anwendung muss mit Microsoft Entra ID registriert sein und über einen App-Schlüssel oder ein X509v2-Zertifikat verfügen, das von Microsoft Entra ID ausgestellt wird. Informationen zum Einrichten einer Anwendung finden Sie unter Bereitstellen einer Microsoft Entra Anwendung.

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

Hinweis

Es wird empfohlen, nach Möglichkeit die Kusto-Clientbibliotheken zu verwenden. Diese Bibliotheken vereinfachen den Authentifizierungsprozess, indem Sie Authentifizierungseigenschaften im Kusto-Verbindungszeichenfolge bereitstellen können.

Durchführen der Authentifizierung im Auftrag von (OBO)

Die Authentifizierung im Auftrag ist relevant, wenn Ihre Webanwendung oder Ihr Dienst als Vermittler zwischen dem Benutzer oder der Anwendung und Ihrem Cluster fungiert.

In diesem Szenario wird einer Anwendung ein Microsoft Entra Zugriffstoken für eine beliebige Ressource gesendet. Anschließend verwendet die Anwendung dieses Token, um ein neues Microsoft Entra-Zugriffstoken für die Azure Data Explorer-Ressource abzurufen. Anschließend kann die Anwendung im Namen des Prinzipals auf Ihren Cluster zugreifen, der durch das ursprüngliche Microsoft Entra-Zugriffstoken angegeben ist. Dieser Flow wird als OAuth 2.0-Authentifizierungsflow im Auftrag der Authentifizierung bezeichnet. In der Regel sind mehrere Konfigurationsschritte mit Microsoft Entra ID erforderlich, und in einigen Fällen ist möglicherweise eine besondere Zustimmung des Administrators des Microsoft Entra Mandanten erforderlich.

So führen Sie die Authentifizierung im Auftrag der Authentifizierung durch:

  1. Stellen Sie eine Microsoft Entra Anwendung zur Verfügung.

  2. Richten Sie eine Vertrauensstellung zwischen der Anwendung und Ihrem Cluster ein. Führen Sie hierzu die Schritte unter Konfigurieren delegierter Berechtigungen aus.

  3. Verwenden Sie in Ihrem Servercode MSAL, um den Tokenaustausch durchzuführen.

    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. Verwenden Sie das Token, um Abfragen auszuführen. Beispiel:

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

Ausführen der Spa-Authentifizierung (Single Page Application)

Verwenden Sie für die Authentifizierung für einen SPA-Webclient den OAuth-Autorisierungscodeflow.

In diesem Szenario wird die App umgeleitet, um sich bei Microsoft Entra-ID anzumelden. Anschließend leitet Microsoft Entra-ID mit einem Autorisierungscode im URI zurück zur App um. Anschließend stellt die App eine Anforderung an den Tokenendpunkt, um das Zugriffstoken abzurufen. Das Token ist 24 Stunden gültig, während derer der Client es wiederverwenden kann, indem das Token unbeaufsichtigt abgerufen wird.

Microsoft Identity Platform verfügt über detaillierte Tutorials für verschiedene Anwendungsfälle wie React, Angular und JavaScript.

So richten Sie die Authentifizierung für einen Webclient ein:

  1. Stellen Sie eine Microsoft Entra Anwendung zur Verfügung.

  2. Konfigurieren Sie die App wie unter MSAL.js 2.0 mit Authentifizierungscodeflow beschrieben.

  3. Verwenden Sie die MSAL.js 2.0-Bibliothek, um einen Benutzer anzumelden und sich bei Ihrem Cluster zu authentifizieren. Microsoft Identity Platform verfügt über detaillierte Tutorials für verschiedene Anwendungsfälle wie React, Angular und JavaScript.

    Im folgenden Beispiel wird die MSAL.js-Bibliothek verwendet, um auf Azure Data Explorer zuzugreifen.

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

Verwandte Inhalte