Compartilhar via

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

  • Artigo

Para autenticar programaticamente com seu cluster, você precisa solicitar um token de acesso de Microsoft Entra ID 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 on-behalf-of (OBO) 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 cenários de autenticação main, as informações a serem fornecidas para autenticação bem-sucedida e o uso da MSAL para autenticação.

Cenários de autenticação

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

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 de 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 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.
Microsoft Entra ID do locatário 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. Microsoft Entra ID 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 Microsoft Entra.

Exemplo: uma organização "Contoso" pode ter a ID 12345678-a123-4567-b890-123a456b789c do locatário e o nome contoso.comde domínio .
URI de autoridade de Microsoft Entra O ponto de extremidade usado para autenticação. O diretório Microsoft Entra ou locatário determina o URI da autoridade de 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/12345678-a123-4567-b890-123a456b789c.

Observação

O ponto de extremidade de serviço Microsoft Entra muda em nuvens nacionais. Ao trabalhar com um serviço de Data Explorer do Azure implantado em uma nuvem nacional, defina o ponto de extremidade de serviço de Microsoft Entra de 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 uma maneira que inicia a interface do usuário de entrada interativa. A appRedirectUri é a URL para a qual Microsoft Entra ID redireciona após a conclusão da autenticação com êxito. 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

  • É recomendável 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 no cadeia de conexão do Kusto.
  • Com as bibliotecas de cliente Kusto, Microsoft Entra tokens são armazenados em um cache de token local no computador do usuário para reduzir o número de vezes que são solicitados a obter 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 Microsoft Entra ID e ter uma chave de aplicativo ou um certificado X509v2 emitido por Microsoft Entra ID. Para configurar um aplicativo, consulte Provisionar um aplicativo 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

É recomendável 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 no cadeia de conexão do Kusto.

Executar autenticação on-behalf-of (OBO)

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

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

Para executar a autenticação em nome de:

  1. Provisionar um aplicativo 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 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 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 spa (aplicativo de página única)

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 no Microsoft Entra ID. Em seguida, Microsoft Entra ID redireciona de volta para o aplicativo com um código de autorização no URI. Em seguida, o aplicativo faz uma solicitação para o ponto de extremidade de 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.

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. Provisionar um aplicativo Microsoft Entra.

  2. Configure o aplicativo conforme descrito em 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 autenticar-se no cluster. 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 de MSAL.js para acessar a Data Explorer do Azure.

    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