Udostępnij za pośrednictwem

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

  • Artykuł

Dotyczy: ✅Microsoft Fabric✅Azure Data Explorer

Aby programowo uwierzytelnić się w klastrze, należy zażądać tokenu dostępu z identyfikatora entra firmy Microsoft specyficznego dla usługi Azure Data Explorer. Ten token dostępu działa jako dowód tożsamości podczas wystawiania żądań do klastra. Do utworzenia tokenu dostępu można użyć jednego z przepływów biblioteki 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 istotne przede wszystkim w aplikacjach internetowych, które wymagają uwierzytelniania w imieniu (OBO) lub uwierzytelniania aplikacji jednostronicowej (SPA). W innych przypadkach zalecamy używanie bibliotek klienckich usługi 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żytkowników: 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 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 token dostępu firmy Microsoft Entra. 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 entra firmy Microsoft Microsoft Entra ID to wielodostępna usługa, a każda organizacja może utworzyć obiekt nazywany katalogiem, który przechowuje obiekty związane z zabezpieczeniami, takie jak konta użytkowników i aplikacje. Identyfikator Entra firmy Microsoft 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 firmy Microsoft Entra.

Przykład: Organizacja "Contoso" może mieć identyfikator aaaabbbb-0000-cccc-1111-dddd2222eeee dzierżawy i nazwę contoso.comdomeny .
Identyfikator URI urzędu Entra firmy Microsoft Punkt końcowy używany do uwierzytelniania. Katalog firmy Microsoft Entra lub dzierżawa określa identyfikator URI urzędu Entra firmy Microsoft. Identyfikator URI to https://login.microsoftonline.com/{tenantId} miejsce, w którym {tenantId} jest identyfikator dzierżawy lub nazwa domeny.

Przykład: na przykład https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee.

Uwaga

Zmiany punktu końcowego usługi Microsoft Entra 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 w chmurze krajowej.

Przeprowadzanie uwierzytelniania użytkowników przy użyciu biblioteki MSAL

Poniższy przykładowy kod pokazuje, jak uzyskać token autoryzacji dla klastra przy użyciu biblioteki MSAL. Autoryzacja jest wykonywana w sposób, który uruchamia interaktywny interfejs użytkownika logowania. To appRedirectUri adres URL, do którego identyfikator Entra firmy Microsoft 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 klienckich 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.
  • Dzięki bibliotekom klienta usługi Kusto tokeny firmy 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 uzyskać token autoryzacji dla klastra przy użyciu biblioteki MSAL. W tym przepływie nie jest wyświetlany żaden monit. Aplikacja musi być zarejestrowana w usłudze Microsoft Entra ID i mieć klucz aplikacji lub certyfikat X509v2 wystawiony przez identyfikator Firmy Microsoft Entra. Aby skonfigurować aplikację, zobacz Aprowizuj aplikację Firmy 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 klienckich 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 mediator między użytkownikiem lub aplikacją a klastrem.

W tym scenariuszu aplikacja jest wysyłana token dostępu firmy Microsoft Entra dla dowolnego zasobu. Następnie aplikacja używa tego tokenu do uzyskania nowego tokenu dostępu firmy 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 firmy Microsoft Entra. Ten przepływ jest nazywany przepływem uwierzytelniania OAuth 2.0 w imieniu. Zazwyczaj wymaga wielu kroków konfiguracji z identyfikatorem Entra firmy Microsoft, a w niektórych przypadkach może wymagać specjalnej zgody administratora dzierżawy firmy Microsoft Entra.

Aby przeprowadzić uwierzytelnianie w imieniu:

  1. Aprowizuj aplikację Firmy 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 Entra firmy Microsoft. Następnie identyfikator Entra firmy Microsoft 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, w trakcie którego klient może użyć go ponownie, 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ę Firmy 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ć 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];

Powiązana zawartość