Métodos de autenticação de aplicativos

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

Esta documentação fornece uma visão geral dos principais métodos de autenticação disponíveis para as bibliotecas de cliente Kusto. Os trechos de código fornecidos demonstram diferentes abordagens para autenticar usuários e aplicativos, permitindo uma interação perfeita com clusters Kusto. Cada método é adequado para diferentes cenários e requisitos.

Sempre que possível, recomendamos o uso de identidades gerenciadas em vez de autenticação de nome de usuário e senha ou cadeias de conexão. As identidades gerenciadas fornecem uma abordagem mais segura e simplificada para a autenticação.

Neste artigo, você aprenderá a autenticar usando:

Pré-requisitos

• Configure seu ambiente de desenvolvimento para usar a biblioteca de cliente Kusto.

Métodos de autenticação do Principal de Aplicação

Esta seção aborda os diferentes métodos de autenticação usando um principal da aplicação.

Autenticação de identidade gerenciada

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

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

• Identidade gerenciada atribuída ao sistema:

  • C#
  • Python
  • TypeScript
  • Java

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

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

  • C#
  • Python
  • TypeScript
  • Java

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

Autenticação baseada em certificado

Os certificados podem servir 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 armazenamento de credenciais local da máquina 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 armazenamento local da máquina é suportado apenas usando C#:

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

  Importante

  Quando se utiliza o nome da entidade e o emissor, o certificado deve ser instalado no armazenamento de certificados da máquina local.

• Certificado de uma fonte arbitrária, como um arquivo em disco, cache ou armazenamento 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, consulte cadeias de conexão Kusto.

Autenticação de chave de aplicativo

A chave do aplicativo, também conhecida como senha do 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 servidor de autorização. É importante gerenciar e proteger com segurança a chave do aplicativo para evitar 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 de aplicação:

  • C#
  • Python
  • TypeScript
  • Java

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

• Cadeia de conexão com 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 do Principal de Utilizador

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

Autenticação interativa de entrada do usuário

Este 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 onde 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.

• Login de usuário interativo:

  • C#
  • Python
  • TypeScript
  • Java

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

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

Esse método de autenticação usa a CLI (Interface de 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 pode 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, consulte Azure Command-Line Interface (CLI).

| 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 de dispositivo

Este método foi concebido para dispositivos sem uma interface de utilizador adequada para início de sessão, tais 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. Este método interativo requer que o utilizador inicie sessão através de um browser.

| 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 do provedor de token personalizado

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 credenciais de Identidade Gerenciada federada

Os 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 identidade gerenciada federada. Você pode modificar o código para atender aos requisitos do seu 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 implemente 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 diferentes métodos de autenticação.

| 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óximo passo