Come eseguire l'autenticazione con Microsoft Authentication Library (MSAL) nelle app

  • Articolo

Per eseguire l'autenticazione a livello di codice con il cluster, è necessario richiedere un token di accesso da Microsoft Entra ID specifico di Azure Esplora dati. Questo token di accesso funge da prova di identità durante l'emissione di richieste al cluster. È possibile usare uno dei flussidi Microsoft Authentication Library (MSAL) per creare un token di accesso.

Questo articolo illustra come usare MSAL per autenticare le entità nel cluster. L'uso diretto di MSAL per autenticare le entità è principalmente rilevante nelle applicazioni Web che richiedono l'autenticazione ON-behalf-of (OBO) o l'autenticazione a pagina singola dell'applicazione a pagina singola. Per altri casi, è consigliabile usare le librerie client Kusto perché semplificano il processo di autenticazione.

In questo articolo vengono illustrati gli scenari di autenticazione principali, le informazioni da fornire per l'autenticazione corretta e l'uso di MSAL per l'autenticazione.

Scenari di autenticazione

Gli scenari di autenticazione principali sono i seguenti:

Per l'autenticazione di utenti e applicazioni, è consigliabile usare le librerie client Kusto. Per l'autenticazione OBO e SPA, le librerie client Kusto non possono essere usate.

Parametri di autenticazione

Durante il processo di acquisizione del token, il client deve fornire i parametri seguenti:

Nome parametro Descrizione
ID risorsa ID risorsa per cui rilasciare il token di accesso Microsoft Entra. L'ID risorsa è l'URI del cluster senza informazioni sulla porta e sul percorso.

Esempio: l'ID risorsa per il help cluster è https://help.kusto.windows.net.
ID tenant Microsoft Entra Microsoft Entra ID è un servizio multi-tenant e ogni organizzazione può creare un oggetto denominato directory che contiene oggetti correlati alla sicurezza, ad esempio account utente e applicazioni. Microsoft Entra ID spesso fa riferimento alla directory come tenant. Ogni tenant ha un ID tenant sotto forma di GUID. In molti casi, il nome di dominio dell'organizzazione può essere usato anche per identificare il tenant Microsoft Entra.

Esempio: un'organizzazione "Contoso" potrebbe avere l'ID 12345678-a123-4567-b890-123a456b789c tenant e il nome contoso.comdi dominio .
URI dell'autorità di Microsoft Entra Endpoint usato per l'autenticazione. La directory Microsoft Entra o il tenant determina l'URI dell'autorità di Microsoft Entra. L'URI è https://login.microsoftonline.com/{tenantId} dove {tenantId} è l'ID tenant o il nome di dominio.

Esempio: ad esempio . https://login.microsoftonline.com/12345678-a123-4567-b890-123a456b789c

Nota

L'endpoint di servizio Microsoft Entra cambia nei cloud nazionali. Quando si usa un servizio di Esplora dati di Azure distribuito in un cloud nazionale, impostare l'endpoint del servizio Microsoft Entra cloud nazionale corrispondente.

Eseguire l'autenticazione utente con MSAL

L'esempio di codice seguente illustra come usare MSAL per ottenere un token di autorizzazione per il cluster. L'autorizzazione viene eseguita in modo da avviare l'interfaccia utente di accesso interattiva. appRedirectUri è l'URL a cui Microsoft Entra ID reindirizza al termine dell'autenticazione. MSAL estrae il codice di autorizzazione da questo reindirizzamento.

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

Nota

  • È consigliabile usare le librerie client Kusto quando possibile. Queste librerie semplificano il processo di autenticazione consentendo di fornire proprietà di autenticazione nel stringa di connessione Kusto.
  • Con le librerie client Kusto, Microsoft Entra token vengono archiviati in una cache di token locale nel computer dell'utente per ridurre il numero di richieste di credenziali. Il file della cache è %APPDATA%\Kusto\userTokenCache.data ed è accessibile solo dall'utente connesso.

Eseguire l'autenticazione dell'applicazione con MSAL

L'esempio di codice seguente illustra come usare MSAL per ottenere un token di autorizzazione per il cluster. In questo flusso non viene visualizzata alcuna richiesta. L'applicazione deve essere registrata con Microsoft Entra ID e avere una chiave dell'app o un certificato X509v2 rilasciato da Microsoft Entra ID. Per configurare un'applicazione, vedere Effettuare il provisioning di un'applicazione 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));

Nota

È consigliabile usare le librerie client Kusto quando possibile. Queste librerie semplificano il processo di autenticazione consentendo di fornire proprietà di autenticazione nel stringa di connessione Kusto.

Eseguire l'autenticazione on-behalf-of (OBO)

L'autenticazione on-behalf-of è rilevante quando l'applicazione Web o il servizio funge da mediatore tra l'utente o l'applicazione e il cluster.

In questo scenario viene inviata un'applicazione a un token di accesso Microsoft Entra per una risorsa arbitraria. L'applicazione usa quindi tale token per acquisire un nuovo token di accesso Microsoft Entra per la risorsa di Azure Esplora dati. L'applicazione può quindi accedere al cluster per conto dell'entità indicata dal token di accesso Microsoft Entra originale. Questo flusso è denominato flusso di autenticazione on-behalf-of OAuth 2.0. In genere richiede più passaggi di configurazione con ID Microsoft Entra e in alcuni casi potrebbe richiedere un consenso speciale dall'amministratore del tenant Microsoft Entra.

Per eseguire l'autenticazione on-behalf-of:

  1. Effettuare il provisioning di un'applicazione Microsoft Entra.

  2. Stabilire una relazione di trust tra l'applicazione e il cluster. A tale scopo, seguire la procedura descritta in Configurare le autorizzazioni delegate.

  3. Nel codice del server usare MSAL per eseguire lo scambio di token.

    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. Usare il token per eseguire query. Ad esempio:

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

Eseguire l'autenticazione dell'applicazione a pagina singola

Per l'autenticazione per un client Web SPA, usare il flusso del codice di autorizzazione OAuth.

In questo scenario, l'app viene reindirizzata per accedere a Microsoft Entra ID. Quindi, Microsoft Entra ID reindirizza all'app con un codice di autorizzazione nell'URI. L'app effettua quindi una richiesta all'endpoint del token per ottenere il token di accesso. Il token è valido per 24 ore durante il quale il client può riutilizzarlo acquisendo il token in modo invisibile all'utente.

Microsoft Identity Platform sono disponibili esercitazioni dettagliate per diversi casi d'uso, ad esempio React, Angular e JavaScript.

Per configurare l'autenticazione per un client Web:

  1. Effettuare il provisioning di un'applicazione Microsoft Entra.

  2. Configurare l'app come descritto in MSAL.js 2.0 con il flusso del codice di autenticazione.

  3. Usare la libreria MSAL.js 2.0 per accedere a un utente ed eseguire l'autenticazione al cluster. Microsoft Identity Platform sono disponibili esercitazioni dettagliate per diversi casi d'uso, ad esempio React, Angular e JavaScript.

    L'esempio seguente usa la libreria di MSAL.js per accedere ad Azure Esplora dati.

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

Contenuti correlati