Autenticación con la biblioteca de autenticación de Microsoft (MSAL) en aplicaciones

  • Artículo

Para autenticarse mediante programación con el clúster, debe solicitar un token de acceso de Microsoft Entra identificador específico de Azure Data Explorer. Este token de acceso actúa como prueba de identidad al emitir solicitudes al clúster. Puede usar uno de los flujos de la Biblioteca de autenticación de Microsoft (MSAL) para crear un token de acceso.

En este artículo se explica cómo usar MSAL para autenticar entidades de seguridad en el clúster. El uso directo de MSAL para autenticar entidades de seguridad es principalmente relevante en las aplicaciones web que requieren autenticación en nombre de (OBO) o autenticación de aplicación de página única (SPA). En otros casos, se recomienda usar las bibliotecas cliente de Kusto a medida que simplifican el proceso de autenticación.

En este artículo, obtendrá información sobre los escenarios de autenticación principales, la información que se va a proporcionar para la autenticación correcta y el uso de MSAL para la autenticación.

Escenarios de autenticación

Los escenarios de autenticación principales son los siguientes:

  • Autenticación de usuario: se usa para comprobar la identidad de los usuarios humanos.

  • Autenticación de la aplicación: se usa para comprobar la identidad de una aplicación que necesita acceder a los recursos sin intervención humana mediante credenciales configuradas.

  • Autenticación en nombre de (OBO): permite que una aplicación intercambie un token para dicha aplicación con un token para acceder a un servicio kusto. Este flujo debe implementarse con MSAL.

  • Autenticación de aplicación de página única (SPA): permite que las aplicaciones web SPA del lado cliente inicien sesión de usuarios y obtengan tokens para acceder al clúster. Este flujo debe implementarse con MSAL.

Para la autenticación de usuario y aplicación, se recomienda usar las bibliotecas cliente de Kusto. Para la autenticación de OBO y SPA, no se pueden usar las bibliotecas cliente de Kusto.

Parámetros de autenticación

Durante el proceso de adquisición de tokens, el cliente debe proporcionar los parámetros siguientes:

Nombre de parámetro Descripción
Id. de recurso Identificador de recurso para el que se va a emitir el token de acceso de Microsoft Entra. El identificador de recurso es el URI del clúster sin información de puerto y ruta de acceso.

Ejemplo: el identificador de recurso del help clúster es https://help.kusto.windows.net.
id. de inquilino de Microsoft Entra Microsoft Entra id. es un servicio multiinquilino y cada organización puede crear un objeto denominado directorio que contenga objetos relacionados con la seguridad, como cuentas de usuario y aplicaciones. Microsoft Entra identificador suele hacer referencia al directorio como inquilino. Cada inquilino tiene un identificador de inquilino en forma de GUID. En muchos casos, el nombre de dominio de la organización también se puede usar para identificar el inquilino de Microsoft Entra.

Ejemplo: una organización "Contoso" podría tener el identificador 12345678-a123-4567-b890-123a456b789c de inquilino y el nombre contoso.comde dominio .
URI de autoridad de Microsoft Entra Punto de conexión utilizado para la autenticación. El directorio Microsoft Entra o el inquilino determina el URI de autoridad de Microsoft Entra. El URI es https://login.microsoftonline.com/{tenantId} donde {tenantId} es el identificador de inquilino o el nombre de dominio.

Ejemplo: por ejemplo, https://login.microsoftonline.com/12345678-a123-4567-b890-123a456b789c.

Nota:

El punto de conexión de servicio Microsoft Entra cambia en las nubes nacionales. Al trabajar con un servicio de Azure Data Explorer implementado en una nube nacional, establezca el punto de conexión de servicio Microsoft Entra nube nacional correspondiente.

Realizar la autenticación de usuario con MSAL

En el ejemplo de código siguiente se muestra cómo usar MSAL para obtener un token de autorización para el clúster. La autorización se realiza de forma que inicie la interfaz de usuario de inicio de sesión interactiva. appRedirectUri es la dirección URL a la que se redirige Microsoft Entra identificador después de que la autenticación se complete correctamente. MSAL extrae el código de autorización de este redireccionamiento.

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:

  • Se recomienda usar las bibliotecas cliente de Kusto siempre que sea posible. Estas bibliotecas simplifican el proceso de autenticación al permitirle proporcionar propiedades de autenticación en el cadena de conexión de Kusto.
  • Con las bibliotecas cliente de Kusto, Microsoft Entra tokens se almacenan en una caché de tokens local en el equipo del usuario para reducir el número de veces que se les solicitan credenciales. El archivo de caché es %APPDATA%\Kusto\userTokenCache.data y solo puede acceder al usuario que ha iniciado sesión.

Realización de la autenticación de aplicaciones con MSAL

En el ejemplo de código siguiente se muestra cómo usar MSAL para obtener un token de autorización para el clúster. En este flujo, no se presenta ninguna solicitud. La aplicación debe registrarse con Microsoft Entra id. y tener una clave de aplicación o un certificado X509v2 emitido por Microsoft Entra ID. Para configurar una aplicación, consulte Aprovisionamiento de una aplicación de 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:

Se recomienda usar las bibliotecas cliente de Kusto siempre que sea posible. Estas bibliotecas simplifican el proceso de autenticación al permitirle proporcionar propiedades de autenticación en el cadena de conexión de Kusto.

Realizar la autenticación en nombre de (OBO)

La autenticación en nombre de es relevante cuando la aplicación web o el servicio actúa como mediador entre el usuario o la aplicación y el clúster.

En este escenario, una aplicación se envía un token de acceso Microsoft Entra para un recurso arbitrario. A continuación, la aplicación usa ese token para adquirir un nuevo token de acceso de Microsoft Entra para el recurso de Azure Data Explorer. A continuación, la aplicación puede acceder al clúster en nombre de la entidad de seguridad indicada por el token de acceso de Microsoft Entra original. Este flujo se denomina flujo de autenticación en nombre de OAuth 2.0. Por lo general, requiere varios pasos de configuración con Microsoft Entra id. y, en algunos casos, podría requerir un consentimiento especial del administrador del inquilino de Microsoft Entra.

Para realizar la autenticación en nombre de:

  1. Aprovisione una aplicación Microsoft Entra.

  2. Establezca una relación de confianza entre la aplicación y el clúster. Para ello, siga los pasos descritos en Configuración de permisos delegados.

  3. En el código de servidor, use MSAL para realizar el intercambio de tokens.

    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. Use el token para ejecutar consultas. Por ejemplo:

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

Realizar la autenticación de aplicación de página única (SPA)

Para la autenticación de un cliente web SPA, use el flujo de código de autorización de OAuth.

En este escenario, la aplicación se redirige para iniciar sesión en Microsoft Entra id. A continuación, Microsoft Entra identificador vuelve a redirigir a la aplicación con un código de autorización en el URI. A continuación, la aplicación realiza una solicitud al punto de conexión del token para obtener el token de acceso. El token es válido durante 24 horas durante la cual el cliente puede reutilizarlo mediante la adquisición silenciosa del token.

Plataforma de identidad de Microsoft tiene tutoriales detallados para diferentes casos de uso, como React, Angular y JavaScript.

Para configurar la autenticación para un cliente web:

  1. Aprovisione una aplicación Microsoft Entra.

  2. Configure la aplicación como se describe en MSAL.js 2.0 con flujo de código de autenticación.

  3. Use la biblioteca MSAL.js 2.0 para iniciar sesión en un usuario y autenticarse en el clúster. Plataforma de identidad de Microsoft tiene tutoriales detallados para diferentes casos de uso, como React, Angular y JavaScript.

    En el ejemplo siguiente se usa la biblioteca MSAL.js para acceder a 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];

Contenido relacionado