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:

principal da aplicação

• Autenticação de Identidade Gerida
• Certificate-Based Autenticação
• Autenticação com chave de aplicação

Principal do Usuário

• Autenticação interativa de entrada do usuário
• de autenticação da Interface de Command-Line do Azure (CLI)
• Autenticação de código de dispositivo

Provedor de token personalizado

• Provedor de Token Personalizado para Autenticação de Credenciais de Identidade Gerenciada Federativa
• Usando o de autenticação TokenCredential do Azure

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#

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

  Python

  kcsb = KustoConnectionStringBuilder
    .with_aad_managed_service_identity_authentication(<QueryEndpointUri>)
  

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

  Java

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

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

  C#

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

  Python

  kcsb = KustoConnectionStringBuilder
    .with_aad_managed_service_identity_authentication(<QueryEndpointUri>, client_id=<ManagedIdentityClientId>)
  

  Observação

  Para usar uma ID de objeto em vez de uma ID de cliente, use o parâmetro object_id.

  const kcsb = KustoConnectionStringBuilder
    .withUserManagedIdentity(<QueryEndpointUri>, <ManagedIdentityClientId>);
  

  Java

  ConnectionStringBuilder kcsb = ConnectionStringBuilder
    .createWithAadManagedIdentity(<QueryEndpointUri>, <ManagedIdentityClientId>);
  

Importante

• O objeto, ou principal, ID do recurso Identidade Gerenciada deve receber uma função para acessar o cluster Kusto. Você pode fazer isso no portal do Azure, na página de recursos do seu cluster Kusto em Segurança + rede>Permissões. A Identidade Gerenciada não deve ser anexada diretamente ao cluster Kusto.
• A autenticação de Identidade Gerenciada não é suportada em ambientes de desenvolvimento local. Para testar a autenticação de Identidade Gerenciada, implante o aplicativo no Azure ou use um método de autenticação diferente ao trabalhar localmente.

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#

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

  Python

  • Certificado carregado na memória:

    kcsb = KustoConnectionStringBuilder
      .with_aad_application_certificate_authentication(<QueryEndpointUri>, <ApplicationId>, <PemPrivateKey>, <CertificateThumbprint>, <AuthorityId>)
    

  • Autenticação de Sujeito e Emissor (SNI)

    kcsb = KustoConnectionStringBuilder
     .with_aad_application_certificate_sni_authentication(<QueryEndpointUri>, <ApplicationId>, <PemPrivateKey>, <PemPublicCertificate>, <CertificateThumbprint>, <AuthorityId>)
    

  • Certificado carregado na memória, como de um ficheiro:

    const certificate: string = await fs.promises.readFile(<privateKeyPemFilePath>, "utf8");
    const kcsb = KustoConnectionStringBuilder
      .withAadApplicationCertificateAuthentication(<QueryEndpointUri>, <ApplicationId>, certificate, <AuthorityId>);
    

  • Certificado carregado de um arquivo:

    const kcsb = KustoConnectionStringBuilder
      .withAadApplicationCertificateAuthentication(<QueryEndpointUri>, <ApplicationId>, undefined, <AuthorityId>, <EnableSubjectAndIssuerAuth>, <PemCertificatePath>);
    

  Java

  • Certificado carregado na memória:

    ConnectionStringBuilder kcsb = ConnectionStringBuilder
      .createWithAadApplicationCertificate(<QueryEndpointUri>, <ApplicationId>, <X509Certificate>, <PrivateKey>, <AuthorityId>);
    

  • Autenticação de Sujeito e Emissor (SNI)

    ConnectionStringBuilder kcsb = ConnectionStringBuilder
      .createWithAadApplicationCertificateSubjectNameIssuer(<QueryEndpointUri>, <ApplicationId>, <PublicCertificateChain>, <PrivateKey>, <AuthorityId>
    

  Para obter mais informações, consulte cadeias de conexão Kusto.

Importante

Para carregar certificados do Cofre de Chaves do Azure, você pode usar o Azure.Security.KeyVault.Certificatescliente.

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#

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

  Python

  kcsb = KustoConnectionStringBuilder
    .with_aad_application_key_authentication(<QueryEndpointUri>, <ApplicationId>, <ApplicationKey>, <AuthorityId>)
  

  const kcsb = KustoConnectionStringBuilder
    .withAadApplicationKeyAuthentication(<QueryEndpointUri>, <ApplicationId>, <ApplicationKey>, <AuthorityId>);
  

  Java

  ConnectionStringBuilder kcsb = ConnectionStringBuilder
    .createWithAadApplicationCredentials(<QueryEndpointUri>, <ApplicationId>, <ApplicationKey>, <AuthorityId>);
  

• Cadeia de conexão com chave do aplicativo:

  C#

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

  Python

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

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

  Java

  String connectionString = "Data Source=<QueryEndpointUri>;AppClientId=<ApplicationId>;AppKey=<ApplicationKey>;Authority Id=<AuthorityId>";
  ConnectionStringBuilder kcsb = new ConnectionStringBuilder(connectionString);
  

Importante

Codificação de segredos no seu código é considerada uma má prática. O armazenamento de informações confidenciais, como credenciais de autenticação, em texto sem formatação pode levar a vulnerabilidades de segurança. Recomendamos que você mantenha as informações confidenciais criptografadas ou armazene-as com segurança em um cofre de chaves. Usando criptografia ou um cofre de chaves, você pode garantir que seus segredos estejam protegidos e acessíveis apenas a usuários ou aplicativos autorizados.

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#

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

  Python

  kcsb = KustoConnectionStringBuilder
    .with_interactive_login(<QueryEndpointUri>)
  

  const kcsb = KustoConnectionStringBuilder
    .createWithUserPrompt(<QueryEndpointUri>, {tenantId: <AuthorityId>});
  

  Java

  ConnectionStringBuilder kcsb = ConnectionStringBuilder
    .createWithAadApplicationCredentials(<QueryEndpointUri>, <AuthorityId>);
  

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.

C#

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

Python

kcsb = KustoConnectionStringBuilder
  .with_az_cli_authentication(<QueryEndpointUri>)

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

Java

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

Importante

Esse método só é suportado para aplicativos .NET Framework.

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.

C#

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;
  });

Python

kcsb = KustoConnectionStringBuilder
  .with_aad_device_authentication(<QueryEndpointUri>)

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

Java

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

Importante

A autenticação do código do dispositivo pode ser bloqueada pelas Políticas de Acesso Condicional do locatário. Se isso ocorrer, selecione um método de autenticação alternativo.

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.

C#

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();
    });

Python

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();
  }
);

Java

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.

C#

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

Python

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);

Java

Não suportado.

Observação

DefaultAzureCredential é usado para autenticar com os serviços do Azure. Ele tenta vários métodos de autenticação para obter um token e pode ser configurado para trabalhar com Identidade Gerenciada, Visual Studio, CLI do Azure e muito mais. Essa credencial é adequada para ambientes de teste e produção, pois pode ser configurada para usar diferentes métodos de autenticação. Para obter mais informações, consulte DefaultAzureCredential Class.

Próximo passo

Criar um aplicativo para executar consultas básicas