Métodos de autenticación de aplicaciones

Se aplica a: ✅Microsoft Fabric✅azure Data Explorer

En este artículo se proporciona información general sobre los métodos de autenticación principales disponibles para las bibliotecas cliente de Kusto. Los fragmentos de código muestran diferentes formas de autenticar usuarios y aplicaciones, lo que permite la interacción sin problemas con los clústeres de Kusto. Cada método se adapta a diferentes escenarios y requisitos.

Use identidades administradas en lugar de autenticación de nombre de usuario y contraseña o cadenas de conexión siempre que sea posible. Las identidades administradas ofrecen un enfoque más seguro y optimizado para la autenticación.

En este artículo, aprenderá a autenticarse mediante:

Autenticación de identidad administrada

• Autenticación basada en certificados
• Autenticación con clave de aplicación

Entidad de seguridad de usuario

• Autenticación de inicio de sesión de usuarios interactivos
• Autenticación con la Interfaz de la línea de comandos (CLI) de Azure
• Autenticación con código de dispositivo

Proveedor de tokens personalizado

• Proveedor de tokens personalizado para la autenticación de credenciales de identidad administrada federada
• Usando la autenticación de Azure TokenCredential

Prerrequisitos

• Configuración del entorno de desarrollo para usar la biblioteca cliente de Kusto

Métodos de autenticación de principal de aplicación

En esta sección se tratan los distintos métodos de autenticación mediante un principal de aplicación.

Autenticación de identidad administrada

Hay dos tipos de identidades administradas: asignadas por el sistema y asignadas por el usuario. Las identidades administradas asignadas por el sistema tienen su ciclo de vida asociado al recurso que los crea. Esta identidad está limitada a un recurso. Las identidades administradas asignadas por el usuario se pueden usar en varios recursos. Para obtener más información, consulte Identidades Administradas.

| En los ejemplos siguientes, reemplace <QueryEndpointUri> y <ManagedIdentityClientId> por sus valores.

• Identidad administrada asignada por el sistema:

  • C#
  • Python
  • TypeScript
  • Java

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

• Identidad administrada asignada por el usuario. Use el identificador de cliente de identidad o el identificador de objeto, como se indica a continuación:

  • C#
  • Python
  • TypeScript
  • Java

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

Autenticación basada en certificados

Los certificados sirven como secretos para autenticar la identidad de una aplicación al solicitar un token. Hay varios métodos para cargar el certificado, como cargarlo desde el almacén de credenciales locales del equipo o desde el disco.

| En los ejemplos siguientes, reemplace <QueryEndpointUri>, <ApplicationId>, <CertificateSubjectName>, <CertificateIssuerName>, <CertificateThumbprint>, <CertificateObject>, <AuthorityId>, <PemPublicCertificate>, <PemPrivateKey>, <privateKeyPemFilePath>, <PemCertificatePath>y <EnableSubjectAndIssuerAuth> por sus propios valores.

• El certificado del almacén de certificados local del equipo solo se admite usando C#.

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

  Importante

  Cuando se utiliza el nombre del sujeto y el emisor, el certificado debe estar instalado en el repositorio de certificados del equipo local.

• Certificado de un origen arbitrario, como un archivo en disco, caché o almacenamiento seguro, como Azure Key Vault. El objeto de certificado debe contener una clave privada:

  • C#
  • Python
  • TypeScript
  • Java

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

  Para obtener más información, consulte Cadenas de conexión de Kusto.

Autenticación de clave de aplicación

La clave de aplicación, también conocida como contraseña de aplicación, es una cadena secreta que una aplicación usa para autenticarse y demostrar su identidad al solicitar un token. Actúa como forma de credencial para que la aplicación acceda a los recursos protegidos. Normalmente, la clave de aplicación se genera y asigna mediante el proveedor de identidades o el servidor de autorización. Es importante administrar y proteger de forma segura la clave de aplicación para evitar el acceso no autorizado a información confidencial o acciones.

| En los ejemplos siguientes, reemplace <QueryEndpointUri>, <ApplicationId>, <ApplicationKey>, <AuthorityId>y <AuthorityId> por sus propios valores.

• Clave de aplicación:

  • C#
  • Python
  • TypeScript
  • Java

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

• Cadena de conexión con clave de aplicación:

  • 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 autenticación de la entidad de seguridad del usuario

En esta sección se tratan los distintos métodos de autenticación mediante un principal de usuario.

Autenticación de inicio de sesión de usuario interactiva

Este método de autenticación usa las credenciales del usuario para establecer una conexión segura con Kusto. El método abre un explorador web donde se le pide al usuario que escriba su nombre de usuario y contraseña para completar el proceso de autenticación.

| En los ejemplos siguientes, reemplace <QueryEndpointUri> ,<AuthorityId>y <AuthorityId> por sus propios valores.

• Inicio de sesión de usuario interactivo:

  • C#
  • Python
  • TypeScript
  • Java

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

Autenticación con la Interfaz de la línea de comandos (CLI) de Azure

Este método de autenticación usa la interfaz de Azure Command-Line (CLI) para autenticar y obtener un token para el usuario. Ejecutar el comando az login significa que el usuario puede establecer de forma segura una conexión y recuperar el token necesario para fines de autenticación. Es posible que se le pida al usuario que inicie sesión si el token no está disponible en la memoria caché de la CLI de Azure y el parámetro interactive está establecido en true. Para obtener más información, consulte Interfaz de la línea de comandos (CLI) de Azure.

| En el ejemplo siguiente, reemplace <QueryEndpointUri> por su propio 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>);

Autenticación de código de dispositivo

Este método está diseñado para dispositivos que carecen de una interfaz de usuario adecuada para el inicio de sesión, como dispositivos IoT y terminales de servidor. Proporciona al usuario un código y una dirección URL para autenticarse mediante un dispositivo diferente, como un smartphone. Este método interactivo requiere que el usuario inicie sesión a través de un explorador.

| En el ejemplo siguiente, reemplace <QueryEndpointUri> por su propio 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 autenticación del proveedor de tokens personalizados

En esta sección se tratan los distintos métodos de autenticación mediante un proveedor de tokens personalizado.

Proveedor de tokens personalizado para la autenticación de credenciales de identidad administrada federada

Se pueden utilizar proveedores de tokens personalizados para adquirir un token de ID de Microsoft Entra con fines de autenticación. En el ejemplo siguiente se muestra cómo usar un proveedor de tokens personalizado para obtener un token mediante la identidad administrada federada. Puede modificar el código para que se ajuste a los requisitos de la aplicación.

| En el ejemplo siguiente, reemplace <AuthorityIdId>, <ApplicationId>, <ManagedIdentityClientId>y <QueryEndpointUri> por sus propios 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);

Uso de la autenticación de Azure TokenCredential

Cree un proveedor de tokens personalizado mediante la creación de una clase que herede de TokenCredential e implemente el método GetToken. Como alternativa, puede usar un proveedor de tokens existente, como DefaultAzureCredential. Este método proporciona flexibilidad para diferentes escenarios de autenticación cuando se requiere un proveedor de tokens personalizado.

Puede usar DefaultAzureCredential para admitir el código de producción que usa la autenticación de identidad administrada o el código de prueba mediante Visual Studio o la CLI de Azure. DefaultAzureCredential puede configurarse para usar diferentes métodos de autenticación.

| En el ejemplo siguiente, reemplace <QueryEndpointUri> y <ManagedIdentityClientId> por sus propios 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);

Paso siguiente