Como autenticar com a Biblioteca de Autenticação da Microsoft (MSAL) nas aplicações

  • Artigo

Para autenticar programaticamente com o cluster, tem de pedir um token de acesso do Microsoft Entra ID específico do Azure Data Explorer. Este token de acesso funciona como prova de identidade ao emitir pedidos para o cluster. Pode utilizar um dos fluxos da Biblioteca de Autenticação da Microsoft (MSAL) para criar um token de acesso.

Este artigo explica como utilizar a MSAL para autenticar principais no cluster. A utilização direta do MSAL para autenticar principais é principalmente relevante em aplicações Web que requerem autenticação Em nome de (OBO) ou autenticação de Aplicação de Página Única (SPA). Noutros casos, recomendamos que utilize as bibliotecas de cliente Kusto , uma vez que simplificam o processo de autenticação.

Neste artigo, saiba mais sobre os principais cenários de autenticação, as informações a fornecer para a autenticação bem-sucedida e a utilização do MSAL para autenticação.

Cenários de autenticação

Os principais cenários de autenticação são os seguintes:

Para autenticação de utilizadores e aplicações, recomendamos a utilização das bibliotecas de cliente Kusto. Para autenticação OBO e SPA, as bibliotecas de cliente Kusto não podem ser utilizadas.

Parâmetros de autenticação

Durante o processo de aquisição de tokens, o cliente tem de fornecer os seguintes parâmetros:

Nome do parâmetro Descrição
ID do Recurso O ID de recurso para o qual emitir o Microsoft Entra token de acesso. O ID do recurso é o URI do cluster sem informações de porta e caminho.

Exemplo: o ID de recurso do help cluster é https://help.kusto.windows.net.
Microsoft Entra ID do inquilino Microsoft Entra ID é um serviço multi-inquilino e todas as organizações podem criar um objeto denominado diretório que contém objetos relacionados com segurança, como contas de utilizador e aplicações. Microsoft Entra ID refere-se frequentemente ao diretório como um inquilino. Cada inquilino tem um ID de inquilino sob a forma de um GUID. Em muitos casos, o nome de domínio da organização também pode ser utilizado para identificar o inquilino Microsoft Entra.

Exemplo: uma organização "Contoso" pode ter o ID 12345678-a123-4567-b890-123a456b789c de inquilino e o nome contoso.comde domínio .
URI da autoridade de Microsoft Entra O ponto final utilizado para autenticação. O diretório Microsoft Entra, ou inquilino, determina o URI da autoridade de Microsoft Entra. O URI é https://login.microsoftonline.com/{tenantId} onde {tenantId} é o ID do inquilino ou o nome de domínio.

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

Nota

O ponto final de serviço Microsoft Entra é alterado nas clouds nacionais. Ao trabalhar com um serviço de Data Explorer do Azure implementado numa cloud nacional, defina o ponto final de serviço de Microsoft Entra de cloud nacional correspondente.

Efetuar a autenticação do utilizador com a MSAL

O seguinte exemplo de código mostra como utilizar a MSAL para obter um token de autorização para o cluster. A autorização é feita de uma forma que inicia a IU de início de sessão interativo. É appRedirectUri o URL para o qual Microsoft Entra ID redireciona após a autenticação ser concluída com êxito. A MSAL extrai o código de autorização deste redirecionamento.

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

  • Recomendamos que utilize as bibliotecas de cliente Kusto sempre que possível. Estas bibliotecas simplificam o processo de autenticação, permitindo-lhe fornecer propriedades de autenticação no cadeia de ligação Kusto.
  • Com as bibliotecas de cliente Kusto, Microsoft Entra tokens são armazenados numa cache de token local no computador do utilizador para reduzir o número de vezes que lhes são pedidas credenciais. O ficheiro de cache é %APPDATA%\Kusto\userTokenCache.data e só pode ser acedido pelo utilizador com sessão iniciada.

Efetuar a autenticação de aplicações com a MSAL

O seguinte exemplo de código mostra como utilizar a MSAL para obter um token de autorização para o cluster. Neste fluxo, não é apresentado nenhum pedido. A aplicação tem de ser registada com Microsoft Entra ID e ter uma chave de aplicação ou um certificado X509v2 emitido por Microsoft Entra ID. Para configurar uma aplicação, veja Aprovisionar uma aplicação 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

Recomendamos que utilize as bibliotecas de cliente Kusto sempre que possível. Estas bibliotecas simplificam o processo de autenticação, permitindo-lhe fornecer propriedades de autenticação no cadeia de ligação Kusto.

Efetuar a autenticação em nome de (OBO)

A autenticação em nome de é relevante quando a sua aplicação Web ou serviço atua como mediador entre o utilizador ou a aplicação e o cluster.

Neste cenário, é enviado um token de acesso Microsoft Entra a uma aplicação para um recurso arbitrário. Em seguida, a aplicação utiliza esse token para adquirir um novo token de acesso Microsoft Entra para o recurso do Azure Data Explorer. Em seguida, a aplicação pode aceder ao cluster em nome do principal indicado pelo token de acesso Microsoft Entra original. Este fluxo é denominado fluxo de autenticação em nome de OAuth 2.0. Geralmente, requer vários passos de configuração com Microsoft Entra ID e, em alguns casos, pode exigir consentimento especial do administrador do inquilino Microsoft Entra.

Para efetuar a autenticação em nome de:

  1. Aprovisionar uma aplicação Microsoft Entra.

  2. Estabeleça uma relação de confiança entre a aplicação e o cluster. Para tal, siga os passos em Configurar permissões delegadas.

  3. No código do servidor, utilize a MSAL para efetuar a troca 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. Utilize o token para executar consultas. Por exemplo:

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

Efetuar a autenticação de Aplicação de Página Única (SPA)

Para autenticação de um cliente Web SPA, utilize o fluxo de código de autorização OAuth.

Neste cenário, a aplicação é redirecionada para iniciar sessão no Microsoft Entra ID. Em seguida, Microsoft Entra ID redireciona novamente para a aplicação com um código de autorização no URI. Em seguida, a aplicação faz um pedido ao ponto final do token para obter o token de acesso. O token é válido durante 24 horas durante o qual o cliente pode reutilizá-lo ao adquirir o token automaticamente.

plataforma de identidades da Microsoft tem tutoriais detalhados para diferentes casos de utilização, como React, Angular e JavaScript.

Para configurar a autenticação para um cliente Web:

  1. Aprovisionar uma aplicação Microsoft Entra.

  2. Configure a aplicação conforme descrito no MSAL.js 2.0 com o fluxo de código de autenticação.

  3. Utilize a biblioteca MSAL.js 2.0 para iniciar sessão num utilizador e autenticar-se no cluster. plataforma de identidades da Microsoft tem tutoriais detalhados para diferentes casos de utilização, como React, Angular e JavaScript.

    O exemplo seguinte utiliza a biblioteca de MSAL.js para aceder ao 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];

Conteúdo relacionado