Compartilhar via

Como autenticar com a MSAL (Biblioteca de Autenticação da Microsoft) em aplicativos

  • Artigo

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer

Para autenticar programaticamente com o cluster, você precisa solicitar um token de acesso da ID do Microsoft Entra específica para o Azure Data Explorer. Esse token de acesso atua como prova de identidade ao emitir solicitações para o cluster. Você pode usar um dos fluxos da MSAL (Biblioteca de Autenticação da Microsoft) para criar um token de acesso.

Este artigo explica como usar a MSAL para autenticar entidades de segurança no cluster. O uso direto da MSAL para autenticar entidades de segurança é relevante principalmente em aplicativos Web que exigem autenticação OBO (em nome de) ou autenticação SPA (Aplicativo de Página Única). Para outros casos, recomendamos usar as bibliotecas de cliente Kusto, pois elas simplificam o processo de autenticação.

Neste artigo, saiba mais sobre os principais cenários de autenticação, as informações a serem fornecidas para uma autenticação bem-sucedida e o uso da MSAL para autenticação.

Cenários de autenticação

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

  • Autenticação do usuário: usada para verificar a identidade de usuários humanos.

  • Autenticação de aplicativo: usada para verificar a identidade de um aplicativo que precisa acessar recursos sem intervenção humana usando credenciais configuradas.

  • Autenticação em nome de (OBO): permite que um aplicativo troque um token por esse aplicativo por um token para acessar um serviço Kusto. Esse fluxo deve ser implementado com a MSAL.

  • Autenticação de aplicativo de página única (SPA): permite que aplicativos Web SPA do lado do cliente conectem usuários e obtenham tokens para acessar seu cluster. Esse fluxo deve ser implementado com a MSAL.

Para autenticação de usuário e aplicativo, recomendamos usar as bibliotecas de cliente Kusto. Para autenticação OBO e SPA, as bibliotecas de cliente Kusto não podem ser usadas.

Parâmetros de autenticação

Durante o processo de aquisição do token, o cliente precisa fornecer os seguintes parâmetros:

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

Exemplo: a ID do recurso para o help cluster é https://help.kusto.windows.net.
ID de locatário do Microsoft Entra O Microsoft Entra ID é um serviço multilocatário e cada organização pode criar um objeto chamado diretório que contém objetos relacionados à segurança, como contas de usuário e aplicativos. A ID do Microsoft Entra geralmente se refere ao diretório como um locatário. Cada locatário tem uma ID de locatário na forma de um GUID. Em muitos casos, o nome de domínio da organização também pode ser usado para identificar o locatário do Microsoft Entra.

Exemplo: uma organização "Contoso" pode ter a ID aaaabbbb-0000-cccc-1111-dddd2222eeee do locatário e o nome contoso.comde domínio.
URI da autoridade do Microsoft Entra O ponto de extremidade usado para autenticação. O diretório do Microsoft Entra, ou locatário, determina o URI de autoridade do Microsoft Entra. O URI é https://login.microsoftonline.com/{tenantId} onde {tenantId} está a ID do locatário ou o nome de domínio.

Exemplo: Por exemplo, https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee.

Observação

O ponto de extremidade de serviço do Microsoft Entra muda em nuvens nacionais. Ao trabalhar com um serviço do Azure Data Explorer implantado em uma nuvem nacional, defina o ponto de extremidade de serviço do Microsoft Entra na nuvem nacional correspondente.

Executar autenticação de usuário com MSAL

O exemplo de código a seguir mostra como usar a MSAL para obter um token de autorização para o cluster. A autorização é feita de forma a iniciar a interface do usuário de entrada interativa. A é a URL para a qual a appRedirectUri ID do Microsoft Entra redireciona após a conclusão bem-sucedida da autenticação. A MSAL extrai o código de autorização desse 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));

Observação

  • Recomendamos usar as bibliotecas de cliente Kusto sempre que possível. Essas bibliotecas simplificam o processo de autenticação, permitindo que você forneça propriedades de autenticação na cadeia de conexão Kusto.
  • Com as bibliotecas de cliente Kusto, os tokens do Microsoft Entra são armazenados em um cache de token local no computador do usuário para reduzir o número de vezes que são solicitadas credenciais. O arquivo de cache é %APPDATA%\Kusto\userTokenCache.data e só pode ser acessado pelo usuário conectado.

Executar autenticação de aplicativo com MSAL

O exemplo de código a seguir mostra como usar a MSAL para obter um token de autorização para o cluster. Nesse fluxo, nenhum prompt é apresentado. O aplicativo deve ser registrado com a ID do Microsoft Entra e ter uma chave de aplicativo ou um certificado X509v2 emitido pela ID do Microsoft Entra. Para configurar um aplicativo, consulte Provisionar um aplicativo do 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));

Observação

Recomendamos usar as bibliotecas de cliente Kusto sempre que possível. Essas bibliotecas simplificam o processo de autenticação, permitindo que você forneça propriedades de autenticação na cadeia de conexão Kusto.

Executar autenticação em nome de (OBO)

A autenticação em nome de é relevante quando seu aplicativo ou serviço Web atua como um mediador entre o usuário ou aplicativo e seu cluster.

Nesse cenário, um aplicativo recebe um token de acesso do Microsoft Entra para um recurso arbitrário. Em seguida, o aplicativo usa esse token para adquirir um novo token de acesso do Microsoft Entra para o recurso do Azure Data Explorer. Em seguida, o aplicativo pode acessar o cluster em nome da entidade de segurança indicada pelo token de acesso original do Microsoft Entra. Esse fluxo é chamado de fluxo de autenticação em nome de OAuth 2.0. Geralmente, ele requer várias etapas de configuração com a ID do Microsoft Entra e, em alguns casos, pode exigir consentimento especial do administrador do locatário do Microsoft Entra.

Para executar a autenticação em nome de:

  1. Provisione um aplicativo do Microsoft Entra.

  2. Estabeleça uma relação de confiança entre o aplicativo e o cluster. Para fazer isso, siga as etapas em Configurar permissões delegadas.

  3. No código do servidor, use a MSAL para executar a troca de 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. Use 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));

Executar autenticação de aplicativo de página única (SPA)

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

Nesse cenário, o aplicativo é redirecionado para entrar na ID do Microsoft Entra. Em seguida, a ID do Microsoft Entra redireciona de volta para o aplicativo com um código de autorização no URI. Em seguida, o aplicativo faz uma solicitação ao ponto de extremidade do token para obter o token de acesso. O token é válido por 24 horas, durante as quais o cliente pode reutilizá-lo adquirindo o token silenciosamente.

A plataforma de identidade da Microsoft tem tutoriais detalhados para diferentes casos de uso, como React, Angular e JavaScript.

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

  1. Provisione um aplicativo do Microsoft Entra.

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

  3. Use a biblioteca MSAL.js 2.0 para conectar um usuário e autenticá-lo no cluster. A plataforma de identidade da Microsoft tem tutoriais detalhados para diferentes casos de uso, como React, Angular e JavaScript.

    O exemplo a seguir usa a biblioteca MSAL.js para acessar o 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