Udostępnij za pośrednictwem

Jak uwierzytelniać się za pomocą biblioteki Microsoft Authentication Library (MSAL) w aplikacjach

  • Artykuł

Aby programowo uwierzytelnić się w klastrze, należy zażądać tokenu dostępu z identyfikatora Microsoft Entra specyficznego dla usługi Azure Data Explorer. Ten token dostępu działa jako dowód tożsamości podczas wysyłania żądań do klastra. Aby utworzyć token dostępu, możesz użyć jednego z przepływówbiblioteki Microsoft Authentication Library (MSAL).

W tym artykule wyjaśniono, jak używać biblioteki MSAL do uwierzytelniania podmiotów zabezpieczeń w klastrze. Bezpośrednie użycie biblioteki MSAL do uwierzytelniania podmiotów zabezpieczeń jest przede wszystkim istotne w aplikacjach internetowych, które wymagają uwierzytelniania w imieniu (OBO) lub uwierzytelniania aplikacji jednostronicowej (SPA). W innych przypadkach zalecamy używanie bibliotek klienta Kusto , ponieważ upraszczają one proces uwierzytelniania.

W tym artykule przedstawiono główne scenariusze uwierzytelniania, informacje dotyczące pomyślnego uwierzytelniania oraz korzystanie z biblioteki MSAL na potrzeby uwierzytelniania.

Scenariusze uwierzytelniania

Główne scenariusze uwierzytelniania są następujące:

  • Uwierzytelnianie użytkownika: służy do weryfikowania tożsamości użytkowników.

  • Uwierzytelnianie aplikacji: służy do weryfikowania tożsamości aplikacji, która musi uzyskiwać dostęp do zasobów bez interwencji człowieka przy użyciu skonfigurowanych poświadczeń.

  • Uwierzytelnianie w imieniu (OBO): umożliwia aplikacji wymianę tokenu dla danej aplikacji przy użyciu tokenu w celu uzyskania dostępu do usługi Kusto. Ten przepływ należy zaimplementować za pomocą biblioteki MSAL.

  • Uwierzytelnianie aplikacji jednostronicowej (SPA): umożliwia aplikacjom internetowym SPA po stronie klienta logowanie użytkowników i uzyskiwanie tokenów w celu uzyskania dostępu do klastra. Ten przepływ należy zaimplementować za pomocą biblioteki MSAL.

W przypadku uwierzytelniania użytkowników i aplikacji zalecamy używanie bibliotek klienckich usługi Kusto. W przypadku uwierzytelniania OBO i SPA nie można używać bibliotek klienckich Usługi Kusto.

Parametry uwierzytelniania

Podczas procesu pozyskiwania tokenu klient musi podać następujące parametry:

Nazwa parametru Opis
Identyfikator zasobu Identyfikator zasobu, dla którego ma być wystawiany Microsoft Entra token dostępu. Identyfikator zasobu to identyfikator URI klastra bez informacji o porcie i ścieżce.

Przykład: identyfikator zasobu klastra help to https://help.kusto.windows.net.
identyfikator dzierżawy Microsoft Entra Microsoft Entra identyfikator jest usługą wielodostępną, a każda organizacja może utworzyć obiekt o nazwie katalog zawierający obiekty związane z zabezpieczeniami, takie jak konta użytkowników i aplikacje. Microsoft Entra identyfikator często odnosi się do katalogu jako dzierżawy. Każda dzierżawa ma identyfikator dzierżawy w postaci identyfikatora GUID. W wielu przypadkach nazwa domeny organizacji może być również używana do obsługi tożsamości dzierżawy Microsoft Entra.

Przykład: Organizacja "Contoso" może mieć identyfikator 12345678-a123-4567-b890-123a456b789c dzierżawy i nazwę contoso.comdomeny .
identyfikator URI urzędu Microsoft Entra Punkt końcowy używany do uwierzytelniania. Katalog Microsoft Entra lub dzierżawa określa identyfikator URI urzędu Microsoft Entra. Identyfikator URI to https://login.microsoftonline.com/{tenantId} gdzie {tenantId} jest identyfikator dzierżawy lub nazwa domeny.

Przykład: na przykład https://login.microsoftonline.com/12345678-a123-4567-b890-123a456b789c.

Uwaga

Punkty końcowe usługi Microsoft Entra zmieniają się w chmurach krajowych. Podczas pracy z usługą Azure Data Explorer wdrożona w chmurze krajowej ustaw odpowiedni punkt końcowy usługi Microsoft Entra chmury krajowej.

Wykonywanie uwierzytelniania użytkownika przy użyciu biblioteki MSAL

Poniższy przykładowy kod pokazuje, jak za pomocą biblioteki MSAL uzyskać token autoryzacji dla klastra. Autoryzacja jest wykonywana w sposób, który uruchamia interakcyjny interfejs użytkownika logowania. Jest appRedirectUri to adres URL, do którego identyfikator Microsoft Entra przekierowuje po pomyślnym zakończeniu uwierzytelniania. Biblioteka MSAL wyodrębnia kod autoryzacji z tego przekierowania.

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

Uwaga

  • Zalecamy używanie bibliotek klienta Kusto zawsze, gdy jest to możliwe. Te biblioteki upraszczają proces uwierzytelniania, umożliwiając udostępnianie właściwości uwierzytelniania w usłudze Kusto parametry połączenia.
  • W przypadku bibliotek klienckich usługi Kusto tokeny Microsoft Entra są przechowywane w lokalnej pamięci podręcznej tokenów na komputerze użytkownika, aby zmniejszyć liczbę monitów o poświadczenia. Plik pamięci podręcznej to %APPDATA%\Kusto\userTokenCache.data i może być dostępny tylko przez zalogowanego użytkownika.

Wykonywanie uwierzytelniania aplikacji przy użyciu biblioteki MSAL

Poniższy przykładowy kod pokazuje, jak za pomocą biblioteki MSAL uzyskać token autoryzacji dla klastra. W tym przepływie nie jest wyświetlany żaden monit. Aplikacja musi być zarejestrowana przy użyciu identyfikatora Microsoft Entra i mieć klucz aplikacji lub certyfikat X509v2 wystawiony przez identyfikator Microsoft Entra. Aby skonfigurować aplikację, zobacz Aprowizuj aplikację 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));

Uwaga

Zalecamy używanie bibliotek klienta Kusto zawsze, gdy jest to możliwe. Te biblioteki upraszczają proces uwierzytelniania, umożliwiając udostępnianie właściwości uwierzytelniania w usłudze Kusto parametry połączenia.

Wykonywanie uwierzytelniania w imieniu (OBO)

Uwierzytelnianie w imieniu jest istotne, gdy aplikacja internetowa lub usługa działa jako pośrednik między użytkownikiem lub aplikacją a klastrem.

W tym scenariuszu aplikacja jest wysyłana Microsoft Entra token dostępu dla dowolnego zasobu. Następnie aplikacja używa tego tokenu do uzyskania nowego tokenu dostępu Microsoft Entra dla zasobu usługi Azure Data Explorer. Następnie aplikacja może uzyskać dostęp do klastra w imieniu podmiotu zabezpieczeń wskazanego przez oryginalny token dostępu Microsoft Entra. Ten przepływ jest nazywany przepływem uwierzytelniania OAuth 2.0 w imieniu. Zazwyczaj wymaga wielu kroków konfiguracji z identyfikatorem Microsoft Entra, a w niektórych przypadkach może wymagać specjalnej zgody od administratora dzierżawy Microsoft Entra.

Aby przeprowadzić uwierzytelnianie w imieniu:

  1. Aprowizuj aplikację Microsoft Entra.

  2. Ustanów relację zaufania między aplikacją a klastrem. W tym celu wykonaj kroki opisane w temacie Konfigurowanie uprawnień delegowanych.

  3. W kodzie serwera użyj biblioteki MSAL do przeprowadzenia wymiany tokenów.

    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. Użyj tokenu do uruchamiania zapytań. Na przykład:

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

Wykonywanie uwierzytelniania aplikacji jednostronicowej (SPA)

Do uwierzytelniania dla klienta internetowego SPA użyj przepływu kodu autoryzacji OAuth.

W tym scenariuszu aplikacja jest przekierowywana do logowania się do identyfikatora Microsoft Entra. Następnie Microsoft Entra identyfikator przekierowuje z powrotem do aplikacji z kodem autoryzacji w identyfikatorze URI. Następnie aplikacja wysyła żądanie do punktu końcowego tokenu w celu uzyskania tokenu dostępu. Token jest ważny przez 24 godziny, podczas którego klient może go ponownie użyć, uzyskując token w trybie dyskretnym.

Platforma tożsamości Microsoft zawiera szczegółowe samouczki dotyczące różnych przypadków użycia, takich jak React, Angular i JavaScript.

Aby skonfigurować uwierzytelnianie dla klienta internetowego:

  1. Aprowizuj aplikację Microsoft Entra.

  2. Skonfiguruj aplikację zgodnie z opisem w MSAL.js 2.0 przy użyciu przepływu kodu uwierzytelniania.

  3. Użyj biblioteki MSAL.js 2.0, aby zalogować się do użytkownika i uwierzytelnić się w klastrze. Platforma tożsamości Microsoft zawiera szczegółowe samouczki dotyczące różnych przypadków użycia, takich jak React, Angular i JavaScript.

    W poniższym przykładzie użyto biblioteki MSAL.js w celu uzyskania dostępu do usługi 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];

Zawartość pokrewna