Freigeben über

So authentifizieren Sie sich mit der Microsoft-Authentifizierungsbibliothek (MSAL) in Apps

  • Artikel

Gilt für: ✅Microsoft Fabric✅Azure Data Explorer

Um sich programmgesteuert bei Ihrem Cluster zu authentifizieren, müssen Sie ein Zugriffstoken von Microsoft Entra-ID für Azure Data Explorer anfordern. Dieses Zugriffstoken fungiert als Identitätsnachweis, wenn Anforderungen an Ihren Cluster ausgestellt werden. Sie können einen der MSAL-Flüsse (Microsoft Authentication Library) verwenden, um ein Zugriffstoken zu erstellen.

In diesem Artikel wird erläutert, wie Sie MSAL zum Authentifizieren von Prinzipalen für Ihren Cluster verwenden. Die direkte Verwendung von MSAL zur Authentifizierung von Prinzipalen ist in erster Linie für Webanwendungen relevant, die die Authentifizierung im Auftrag von (OBO) oder die Authentifizierung von Einzelseitenanwendungen (Single Page Application, SPA) erfordern. In anderen Fällen empfehlen wir die Verwendung der Kusto-Clientbibliotheken , da sie den Authentifizierungsprozess vereinfachen.

In diesem Artikel erfahren Sie mehr über die wichtigsten Authentifizierungsszenarien, die Informationen für eine erfolgreiche Authentifizierung und die Verwendung von MSAL für die Authentifizierung.

Authentifizierungsszenarien

Die wichtigsten 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 menschliche Intervention auf Ressourcen zugreifen muss, indem konfigurierte Anmeldeinformationen verwendet werden.

  • Authentifizierung im Auftrag von (OBO): Ermöglicht einer Anwendung, ein Token für die besagte Anwendung mit einem Token auszutauschen, um auf einen Kusto-Dienst zuzugreifen. Dieser Fluss 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 Fluss 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 Tokenerwerbs muss der Client die folgenden Parameter bereitstellen:

Parametername Beschreibung
Ressourcen-ID Die Ressourcen-ID, für die das Microsoft Entra-Zugriffstoken ausgibt. Die Ressourcen-ID ist der Cluster-URI ohne Portinformationen und Pfad.

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

Beispiel: Eine Organisation "Contoso" kann über die Mandanten-ID aaaabbbb-0000-cccc-1111-dddd2222eeee und den Domänennamen contoso.comverfügen.
Microsoft Entra authority URI Der für die Authentifizierung verwendete Endpunkt. Das Microsoft Entra-Verzeichnis oder der Mandant bestimmt den URI der Microsoft Entra-Autorität. Der URI ist https://login.microsoftonline.com/{tenantId} {tenantId} entweder die Mandanten-ID oder der Domänenname.

Beispiel: Beispiel https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee: .

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 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, zu der die Microsoft Entra-ID nach erfolgreichem Abschluss der Authentifizierung umleitet. 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

  • Wir empfehlen, die Kusto-Clientbibliotheken nach Möglichkeit zu verwenden. Diese Bibliotheken vereinfachen den Authentifizierungsprozess, indem Sie Authentifizierungseigenschaften im Kusto-Verbindungszeichenfolge bereitstellen können.
  • Mit den Kusto-Clientbibliotheken werden Microsoft Entra-Token in einem lokalen Tokencache auf dem Computer des Benutzers gespeichert, um zu verringern, wie oft sie zur Eingabe von Anmeldeinformationen aufgefordert werden. Die Cachedatei ist %APPDATA%\Kusto\userTokenCache.data und kann nur vom angemeldeten Benutzer aufgerufen 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 Fluss wird keine Eingabeaufforderung angezeigt. Die Anwendung muss mit der Microsoft Entra-ID registriert sein und über einen App-Schlüssel oder ein X509v2-Zertifikat verfügen, das von der Microsoft Entra-ID ausgestellt wurde. 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

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

Durchführen der Authentifizierung im Auftrag von (OBO)

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

In diesem Szenario wird eine 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 Auftrag des Prinzipals, der durch das ursprüngliche Microsoft Entra-Zugriffstoken angegeben ist, auf Ihren Cluster zugreifen. Dieser Fluss wird als OAuth 2.0 im Auftrag des Authentifizierungsflusses 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 aus:

  1. Stellen Sie eine Microsoft Entra-Anwendung bereit.

  2. Richten Sie eine Vertrauensstellung zwischen der Anwendung und Ihrem Cluster ein. Führen Sie dazu 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. Zum Beispiel:

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

Durchführen der Single Page Application (SPA)-Authentifizierung

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

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

Microsoft Identity Platform enthält detaillierte Lernprogramme 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 bereit.

  2. Konfigurieren Sie die App wie in MSAL.js 2.0 beschrieben mit Authentifizierungscodefluss.

  3. Verwenden Sie die MSAL.js 2.0-Bibliothek, um sich bei einem Benutzer anzumelden und sich bei Ihrem Cluster zu authentifizieren. Microsoft Identity Platform enthält detaillierte Lernprogramme 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];

Zugehöriger Inhalt