Методы проверки подлинности приложений

Переключайте службы с помощью раскрывающегося списка Версия. Дополнительные сведения о навигации.
Область применения: ✅ Microsoft Fabric ✅ Azure Data Explorer

В этой статье представлен обзор основных методов проверки подлинности, доступных для клиентских библиотек Kusto. Фрагменты кода показывают различные способы проверки подлинности пользователей и приложений, что позволяет легко взаимодействовать с кластерами Kusto. Каждый метод подходит для различных сценариев и требований.

По возможности используйте управляемые удостоверения вместо имени пользователя, аутентификации с использованием пароля или строк подключения. Управляемые удостоверения обеспечивают более безопасный и упрощенный подход к проверке подлинности.

Из этой статьи вы узнаете, как выполнить проверку подлинности с помощью:

Проверка подлинности управляемого удостоверения

• Аутентификация на основе сертификата
• Проверка подлинности ключа приложения

Главный пользователь

• Интерактивная проверка подлинности входа пользователей
• Проверка подлинности интерфейса Command-Line Azure (CLI)
• проверка подлинности кода устройства

Поставщик пользовательских токенов

• Настраиваемый поставщик токенов для аутентификации с помощью учетных данных федеративной управляемой идентификации
• Использование проверки подлинности токена Azure TokenCredential

Предпосылки

• Настройка среды разработки для использования клиентской библиотеки Kusto

Методы проверки подлинности субъекта приложения

В этом разделе рассматриваются различные методы аутентификации с использованием учетной записи приложения.

Аутентификация управляемой идентификации

Существует два типа управляемых удостоверений: назначаемые системой и назначаемые пользователем. Управляемые удостоверения, назначаемые системой, имеют жизненный цикл, который зависит от ресурса, создающего их. Это идентификация ограничена одним ресурсом. Назначаемые пользователем управляемые удостоверения могут использоваться для нескольких ресурсов. Дополнительные сведения см. в разделе Управляемые удостоверения.

В следующих примерах замените <QueryEndpointUri> и <ManagedIdentityClientId> вашими значениями.

• Управляемое удостоверение, назначаемое системой:

  • C#
  • Python
  • TypeScript
  • Java

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

• Управляемая пользователем назначенная идентичность Используйте идентификатор клиента идентификации или идентификатор объекта, как показано ниже.

  • C#
  • Python
  • TypeScript
  • Java

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

Проверка подлинности на основе сертификатов

Сертификаты служат секретами для аутентификации приложения при запросе токена. Существует несколько методов загрузки сертификата, таких как загрузка сертификата из локального хранилища учетных данных компьютера или с диска.

| В следующих примерах замените <QueryEndpointUri>, <ApplicationId><CertificateSubjectName><CertificateIssuerName><CertificateThumbprint><CertificateObject><AuthorityId><PemPublicCertificate>, <PemPrivateKey><privateKeyPemFilePath><PemCertificatePath>, и <EnableSubjectAndIssuerAuth> собственными значениями.

• Сертификат из локального хранилища сертификатов компьютера поддерживается только с помощью C#:

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

  Это важно

  При использовании имени субъекта и издателя сертификат должен быть установлен в хранилище сертификатов локального компьютера.

• Сертификат из произвольного источника, например файл на диске, кэше или безопасном хранилище, например Azure Key Vault. Объект сертификата должен содержать закрытый ключ:

  • C#
  • Python
  • TypeScript
  • Java

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

  Дополнительные сведения см. в разделе "Строки подключения Kusto".

Проверка подлинности ключа приложения

Ключ приложения, также известный как пароль приложения, является секретной строкой, которую приложение использует для проверки подлинности и подтверждения идентичности при запросе токена. Он служит формой учетных данных для приложения для доступа к защищенным ресурсам. Ключ приложения обычно создается и назначается поставщиком удостоверений или сервером авторизации. Важно безопасно управлять ключом приложения и защищать его, чтобы предотвратить несанкционированный доступ к конфиденциальной информации или действиям.

| В следующих примерах замените <QueryEndpointUri>, <ApplicationId><ApplicationKey>, <AuthorityId>и <AuthorityId> собственными значениями.

• Ключ приложения:

  • C#
  • Python
  • TypeScript
  • Java

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

• Строка подключения с ключом приложения:

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

Методы проверки подлинности главного пользователя

В этом разделе рассматриваются различные методы проверки подлинности с помощью учетной записи пользователя.

Интерактивная проверка подлинности входа пользователей

Этот метод проверки подлинности использует учетные данные пользователя для установления безопасного подключения к Kusto. Метод открывает веб-браузер, в котором пользователю предлагается ввести имя пользователя и пароль, чтобы завершить процесс проверки подлинности.

| В следующих примерах замените <QueryEndpointUri> ,<AuthorityId>и <AuthorityId> собственными значениями.

• Интерактивный вход пользователя:

  • C#
  • Python
  • TypeScript
  • Java

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

Проверка подлинности интерфейса Command-Line Azure (CLI)

Этот метод аутентификации использует Azure Command-Line Interface (CLI) для аутентификации пользователей и получения токена. az login Выполнение команды означает, что пользователь может безопасно установить подключение и получить необходимый маркер для проверки подлинности. Пользователю может потребоваться выполнить вход, если маркер недоступен в кэше Azure CLI, а параметр interactive задан как true. Для получения дополнительной информации см. Azure Command-Line Interface (CLI).

В следующем примере замените <QueryEndpointUri> на собственное значение.

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

аутентификация с помощью кода устройства;

Этот метод предназначен для устройств, не имеющих соответствующего пользовательского интерфейса для входа, например устройств Интернета вещей и терминалов сервера. Он предоставляет пользователю код и URL-адрес для проверки подлинности с помощью другого устройства, например смартфона. Этот интерактивный метод требует, чтобы пользователь войдите через браузер.

В следующем примере замените <QueryEndpointUri> на собственное значение.

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

Методы аутентификации с использованием пользовательских поставщиков токенов

В этом разделе рассматриваются различные методы аутентификации с помощью пользовательского провайдера токенов.

Поставщик пользовательских токенов для авторизации учетных данных федеративной управляемой идентификации.

Пользовательские поставщики токенов могут использоваться для получения токена Microsoft Entra ID для аутентификации. В следующем примере показано, как использовать настраиваемый поставщик маркеров для получения маркера с помощью федеративного управляемого удостоверения. Вы можете изменить код в соответствии с требованиями приложения.

| В следующем примере замените <AuthorityIdId>, <ApplicationId><ManagedIdentityClientId>и <QueryEndpointUri> на собственные значения.

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

Использование аутентификации с помощью Azure TokenCredential

Создайте пользовательского поставщика маркеров, создав класс, который наследует от TokenCredential и реализует метод GetToken. Кроме того, можно использовать существующего поставщика токенов, например DefaultAzureCredential. Этот метод обеспечивает гибкость для различных сценариев аутентификации, когда необходим пользовательский поставщик токенов.

Вы можете использовать DefaultAzureCredential для поддержки рабочего кода, использующего проверку подлинности управляемого удостоверения, или тестирования кода с помощью Visual Studio или Azure CLI. DefaultAzureCredential можно настроить для использования различных методов проверки подлинности.

В следующем примере замените <QueryEndpointUri> и <ManagedIdentityClientId> на ваши собственные значения.

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

Следующий шаг