Métodos de autenticação de aplicativo

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

Este artigo fornece uma visão geral dos métodos de autenticação primários disponíveis para as bibliotecas de clientes do Kusto. Os snippets de código mostram diferentes maneiras de autenticar usuários e aplicativos, permitindo a interação perfeita com clusters Kusto. Cada método atende a diferentes cenários e requisitos.

Use identidades gerenciadas em vez de autenticação de nome de usuário e senha ou cadeias de conexão sempre que possível. As identidades gerenciadas oferecem uma abordagem mais segura e simplificada para autenticação.

Neste artigo, você aprenderá a autenticar usando:

Autenticação de identidade gerenciada

• Autenticação baseada em certificado
• Autenticação de chave de aplicativo

Usuário principal

• autenticação interativa de login do usuário
• Autenticação da CLI (interface de linha de comando do Azure)
• Autenticação de código do dispositivo

Provedor de token personalizado

• Provedor de token personalizado para autenticação de credencial de identidade gerenciada federada
• Usando a autenticação TokenCredential do Azure

Pré-requisitos

• Configurar seu ambiente de desenvolvimento para usar a biblioteca de clientes do Kusto

Métodos de autenticação de principal de aplicativo

Esta seção aborda os diferentes métodos de autenticação usando uma entidade de segurança do aplicativo.

Autenticação de identidade gerenciada

Há dois tipos de identidades gerenciadas: atribuídas pelo sistema e atribuídas pelo usuário. As identidades gerenciadas atribuídas pelo sistema têm seu ciclo de vida vinculado ao recurso que as cria. Essa identidade é limitada a um recurso. As identidades gerenciadas atribuídas pelo usuário podem ser usadas em vários recursos. Para obter mais informações, consulte Identidades Gerenciadas.

| Nos exemplos a seguir, substitua <QueryEndpointUri> e <ManagedIdentityClientId> com seus valores.

• Identidade gerenciada atribuída pelo sistema:

  • C#
  • Python
  • TypeScript
  • Java

  var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
    .WithAadSystemManagedIdentity();
  

• Identidade gerenciada atribuída pelo usuário. Use a ID do cliente de identidade ou a ID do objeto, da seguinte maneira:

  • C#
  • Python
  • TypeScript
  • Java

  var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
    .WithAadUserManagedIdentity(<ManagedIdentityClientId>);
  

Autenticação baseada em certificado

Os certificados servem como segredos para autenticar a identidade de um aplicativo ao solicitar um token. Há vários métodos para carregar o certificado, como carregá-lo do repositório de credenciais local do computador ou do disco.

| Nos exemplos a seguir, substitua <QueryEndpointUri>, <ApplicationId>, <CertificateSubjectName>, <CertificateIssuerName>, <CertificateThumbprint>, <CertificateObject>, <AuthorityId>, <PemPublicCertificate>, <PemPrivateKey>, <privateKeyPemFilePath>, <PemCertificatePath>e <EnableSubjectAndIssuerAuth> com seus próprios valores.

• O certificado do repositório de certificados local do computador só tem suporte usando C#:

  var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
    .WithAadApplicationSubjectAndIssuerAuthentication(<ApplicationId>, <CertificateSubjectName>, <CertificateIssuerName>, <AuthorityId>);
  

  Importante

  Quando você usa o nome da entidade e o emissor, o certificado deve ser instalado no repositório de certificados do computador local.

• Certificado de uma origem arbitrária, como um arquivo em disco, cache ou repositório seguro, como o Azure Key Vault. O objeto de certificado deve conter uma chave privada:

  • C#
  • Python
  • TypeScript
  • Java

  X509Certificate2 certificate = <CertificateObject>;
  var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
    .WithAadApplicationCertificateAuthentication(<ApplicationId>, certificate, <AuthorityId>);
  

  Para obter mais informações, confira Cadeias de conexão do Kusto.

Autenticação de chave de aplicativo

A chave do aplicativo, também conhecida como senha de aplicativo, é uma cadeia de caracteres secreta que um aplicativo usa para autenticar e provar sua identidade ao solicitar um token. Ele serve como uma forma de credencial para o aplicativo acessar recursos protegidos. A chave do aplicativo normalmente é gerada e atribuída pelo provedor de identidade ou pelo servidor de autorização. É importante gerenciar e proteger com segurança a chave do aplicativo para impedir o acesso não autorizado a informações ou ações confidenciais.

| Nos exemplos a seguir, substitua <QueryEndpointUri>, <ApplicationId>, <ApplicationKey>, <AuthorityId>e <AuthorityId> por seus próprios valores.

• Chave do aplicativo:

  • C#
  • Python
  • TypeScript
  • Java

  var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
    .WithAadApplicationKeyAuthentication(<ApplicationId>, <ApplicationKey>, <AuthorityId>);
  

• Cadeia de conexão com a chave do aplicativo:

  • C#
  • Python
  • TypeScript
  • Java

  var connectionString = "Data Source=<QueryEndpointUri>;Initial Catalog=NetDefaultDB;AAD Federated Security=True;AppClientId=<ApplicationId>;AppKey=<ApplicationKey>;Authority Id=<AuthorityId>;"
  var kcsb = new KustoConnectionStringBuilder(connectionString);
  

Métodos de autenticação da entidade de usuário

Esta seção aborda os diferentes métodos de autenticação usando uma entidade de usuário.

Autenticação interativa de entrada do usuário

Esse método de autenticação usa as credenciais do usuário para estabelecer uma conexão segura com o Kusto. O método abre um navegador da Web em que o usuário é solicitado a inserir seu nome de usuário e senha para concluir o processo de autenticação.

| Nos exemplos a seguir, substitua <QueryEndpointUri>,<AuthorityId>e <AuthorityId> por seus próprios valores.

• Entrada interativa do usuário:

  • C#
  • Python
  • TypeScript
  • Java

  var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
    .WithAadUserPromptAuthentication();
  

Autenticação da CLI (Interface Command-Line) do Azure

Esse método de autenticação usa a CLI (Interface Command-Line) do Azure para autenticar e obter um token para o usuário. Executar o comando az login significa que o usuário pode estabelecer uma conexão com segurança e recuperar o token necessário para fins de autenticação. O usuário poderá ser solicitado a entrar se o token não estiver disponível no cache da CLI do Azure e o parâmetro interactive estiver definido como true. Para obter mais informações, confira CLI (interface de linha de comando) do Azure.

| No exemplo a seguir, substitua <QueryEndpointUri> pelo seu próprio valor.

var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
  .WithAadAzCliAuthentication(interactive: true);

kcsb = KustoConnectionStringBuilder
  .with_az_cli_authentication(<QueryEndpointUri>)

const kcsb = KustoConnectionStringBuilder
  .withAzLoginIdentity(<QueryEndpointUri>);

ConnectionStringBuilder kcsb = ConnectionStringBuilder
  .createWithAzureCli(<QueryEndpointUri>);

Autenticação de código do dispositivo

Esse método foi projetado para dispositivos sem uma interface de usuário adequada para entrada, como dispositivos IoT e terminais de servidor. Ele fornece ao usuário um código e uma URL para autenticar usando um dispositivo diferente, como um smartphone. Esse método interativo requer que o usuário entre por meio de um navegador.

| No exemplo a seguir, substitua <QueryEndpointUri> pelo seu próprio valor.

var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
  .WithAadDeviceCodeAuthentication((msg, uri, code) =>
  {
    // The callback is used to display instructions to the user on how to authenticate using the device code
    Console.WriteLine("Device Code Message: {0}", msg);
    Console.WriteLine("Device Code Uri: {0}", uri);
    Console.WriteLine("Device Code: {0}", code);

    return Task.CompletedTask;
  });

kcsb = KustoConnectionStringBuilder
  .with_aad_device_authentication(<QueryEndpointUri>)

const kcsb = KustoConnectionStringBuilder
  .withAadDeviceAuthentication(<QueryEndpointUri>);

ConnectionStringBuilder kcsb = ConnectionStringBuilder
  .createWithDeviceCode(<QueryEndpointUri>);

Métodos de autenticação para provedores personalizados de token

Esta seção aborda os diferentes métodos de autenticação usando um provedor de token personalizado.

Provedor de token personalizado para autenticação de credencial de Identidade Gerenciada federada

Provedores de token personalizados podem ser usados para adquirir um token de ID do Microsoft Entra para autenticação. O exemplo a seguir demonstra como usar um provedor de token personalizado para obter um token usando a identidade gerenciada federada. Você pode modificar o código para atender aos requisitos do aplicativo.

| No exemplo a seguir, substitua <AuthorityIdId>, <ApplicationId>, <ManagedIdentityClientId>e <QueryEndpointUri> por seus próprios valores.

public class TokenProvider
{
  private ClientAssertionCredential m_clientAssertion;
  private TokenRequestContext m_tokenRequestContext;

  public TokenProvider(string queryEndpointUri)
  {
    string resourceId = null;

    try
    {
      // Get the appropiate resource id by querying the metadata
      var httpClient = new HttpClient();
      var response = httpClient.GetByteArrayAsync($"{queryEndpointUri}/v1/rest/auth/metadata").Result;
      var json = JObject.Parse(Encoding.UTF8.GetString(response));
      resourceId = json["AzureAD"]?["KustoServiceResourceId"]?.ToString();
      // Append scope to resource id
      resourceId = !string.IsNullOrWhiteSpace(resourceId) ? $"{resourceId}/.default" : null;
    }
    catch { /* Handle exception */}

    m_tokenRequestContext = new TokenRequestContext(new string[] { resourceId ?? "https://kusto.kusto.windows.net/.default" });

    // Create client assertion credential to authenticate with Kusto
    m_clientAssertion = new ClientAssertionCredential
    (
      <AuthorityIdId>,
      <ApplicationId>,
      async (token) =>
      {
        // Get Managed Identity token
        var miCredential = new ManagedIdentityCredential(<ManagedIdentityClientId>);
        var miToken = await miCredential.GetTokenAsync(new TokenRequestContext(new[] {
          "api://AzureADTokenExchange/.default"
        })).ConfigureAwait(false);
        return miToken.Token;
      }
    );
  }

  public async Task<string> GetTokenAsync()
  {
    var accessToken = await m_clientAssertion.GetTokenAsync(m_tokenRequestContext).ConfigureAwait(false);
    return accessToken.Token;
  }
}

var tokenProvider = new TokenProvider(<QueryEndpointUri>);

var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
  .WithAadTokenProviderAuthentication(
    async () =>
    {
      return await tokenProvider.GetTokenAsync();
    });

import requests
from azure.identity import ClientAssertionCredential, ManagedIdentityCredential
from azure.kusto.data import KustoConnectionStringBuilder

class TokenProvider:
  def __init__(self, query_endpoint_uri):
    self.query_endpoint_uri = query_endpoint_uri
    self.resource_id = None
    self.token_request_context = None
    self.client_assertion = None
    self._initialize()

  def _initialize(self):
    try:
      # Get the appropriate resource id by querying the metadata
      response = requests.get(f"{self.query_endpoint_uri}/v1/rest/auth/metadata")
      json = response.json()
      self.resource_id = json.get("AzureAD", {}).get("KustoServiceResourceId", "https://kusto.kusto.windows.net")
      # Append scope to resource id
      self.resource_id = f"{self.resource_id}/.default"
    except Exception as error:
      print(f"Error fetching metadata: {error}")

    self.token_request_context = {"scopes": [self.resource_id or "https://kusto.kusto.windows.net/.default"]}

    # Create client assertion credential to authenticate with Kusto
    self.client_assertion = ClientAssertionCredential(
      tenant_id="<AuthorityId>"
      client_id="<ApplicationId>",
      func=self._get_managed_identity_token
    )

  async def _get_managed_identity_token(self):
    mi_credential = ManagedIdentityCredential()
    mi_token = await mi_credential.get_token("api://AzureADTokenExchange/.default")
    return mi_token.token

  async def get_token_async(self):
    access_token = await self.client_assertion.get_token(self.token_request_context)
    return access_token.token

def main():
  query_endpoint_uri = "<QueryEndpointUri>"
  token_provider = TokenProvider(query_endpoint_uri)
  kcsb = KustoConnectionStringBuilder.with_token_provider(
    query_endpoint_uri,
    token_provider.get_token_async
  )

import { ManagedIdentityCredential, ClientAssertionCredential } from '@azure/identity';
import get from 'axios';
import { KustoConnectionStringBuilder } from 'azure-kusto-data';

class TokenProvider {
  constructor(queryEndpointUri) {
    this.queryEndpointUri = queryEndpointUri;
    this.resourceId = null;
    this.tokenRequestContext = null;
    this.clientAssertion = null;
  }

  async initialize() {
    try {
      // Get the appropriate resource id by querying the metadata
      const response = await get(`${this.queryEndpointUri}/v1/rest/auth/metadata`);
      const json = response.data;
      this.resourceId = json.AzureAD?.KustoServiceResourceId || 'https://kusto.kusto.windows.net';
      // Append scope to resource id
      this.resourceId = `${this.resourceId}/.default`;
    } catch (error) {
      console.error('Error fetching metadata:', error);
    }

    this.tokenRequestContext = { scopes: [this.resourceId || 'https://kusto.kusto.windows.net/.default'] };

    // Create client assertion credential to authenticate with Kusto
    this.clientAssertion = new ClientAssertionCredential(
      '<AuthorityId>', // tenantId
      '<ApplicationId>', // clientId
      async () => {
        const miCredential = new ManagedIdentityCredential();
        const miToken = await miCredential.getToken({ scopes: ['api://AzureADTokenExchange/.default'] });
        return miToken.token;
      }
    );
  }

  async getTokenAsync() {
    const accessToken = await this.clientAssertion.getToken(this.tokenRequestContext);
    return accessToken.token;
  }
}

const tokenProvider = new TokenProvider("<QueryEndpointUri>");
await tokenProvider.initialize();

const kcsb = KustoConnectionStringBuilder.withAadTokenProviderAuthentication(
  "<QueryEndpointUri>",
  async () => {
    return await tokenProvider.getTokenAsync();
  }
);

public class TokenProvider {
  private TokenRequestContext tokenRequestContext;
  private ClientAssertionCredential clientAssertion;

  public TokenProvider(String queryEndpointUri) {
    String resourceId = "";
    try {
      // Get the appropriate resource id by querying the metadata
      URL url = new URL(queryEndpointUri + "/v1/rest/auth/metadata");
      HttpURLConnection conn = (HttpURLConnection) url.openConnection();
      conn.setRequestMethod("GET");
      conn.connect();

      Scanner scanner = new Scanner(url.openStream(), StandardCharsets.UTF_8);
      String jsonResponse = scanner.useDelimiter("\\A").next();
      scanner.close();

      ObjectMapper mapper = new ObjectMapper();
      JsonNode jsonNode = mapper.readTree(jsonResponse);
      resourceId = jsonNode.path("AzureAD").path("KustoServiceResourceId").asText("https://kusto.kusto.windows.net");
      // Append scope to resource id
      resourceId = resourceId + "/.default";
    } catch (IOException e) {
      System.err.println("Error fetching metadata: " + e.getMessage());
      resourceId = "https://kusto.kusto.windows.net/.default";
    }

    tokenRequestContext = new TokenRequestContext().addScopes(resourceId);

    // Create client assertion credential to authenticate with Kusto
    clientAssertion = new ClientAssertionCredential(
      "<AuthorityId>",
      "<ApplicationId>", // clientId
      () -> {
        ManagedIdentityCredential miCredential = new ManagedIdentityCredential();
        return miCredential.getToken(new TokenRequestContext().addScopes("api://AzureADTokenExchange/.default")).block().getToken();
      }
    );
  }

  public CompletableFuture<String> getTokenAsync() {
    return clientAssertion.getToken(tokenRequestContext).thenApply(token -> token.getToken());
  }   
}

TokenProvider tokenProvider = new TokenProvider("<QueryEndpointUri>");
ConnectionStringBuilder kcsb = ConnectionStringBuilder.createWithAadTokenProviderAuthentication(queryEndpointUri,tokenProvider::getTokenAsync);

Usando a autenticação tokenCredential do Azure

Crie um provedor de token personalizado criando uma classe que herda de TokenCredential e implementa o método GetToken. Como alternativa, você pode usar um provedor de token existente como DefaultAzureCredential. Esse método fornece flexibilidade para diferentes cenários de autenticação quando um provedor de token personalizado é necessário.

Você pode usar DefaultAzureCredential para dar suporte ao código de produção que usa a autenticação de Identidade Gerenciada ou testar o código usando o Visual Studio ou a CLI do Azure. DefaultAzureCredential pode ser configurado para usar métodos de autenticação diferentes.

| No exemplo a seguir, substitua <QueryEndpointUri> e <ManagedIdentityClientId> por seus próprios valores.

var credentialProvider = new DefaultAzureCredential(new DefaultAzureCredentialOptions {
  ManagedIdentityClientId = <ManagedIdentityClientId>
 });
var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
  .WithAadAzureTokenCredentialsAuthentication(credentialProvider);

from azure.identity import DefaultAzureCredential
token_credential = DefaultAzureCredential()
kcsb = KustoConnectionStringBuilder
  .with_azure_token_credential(<QueryEndpointUri>, token_credential)

import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();
const kcsb = KustoConnectionStringBuilder
  .withTokenCredential(<QueryEndpointUri>, credential);

Próxima etapa