应用的身份验证方法

使用 “版本 ”下拉列表切换服务。 了解有关导航的详细信息
适用于:✅ Azure Data Explorer

本文概述了 Kusto 客户端库可用的主要身份验证方法。 代码片段显示了对用户和应用进行身份验证的不同方法,从而与 Kusto 群集实现无缝交互。 每个方法都适合不同的方案和要求。

尽可能使用托管标识,而不是用户名和密码身份验证或连接字符串。 托管标识提供更安全且简化的身份验证方法。

本文介绍如何使用以下各项进行身份验证:

应用程序主体

托管标识身份验证

用户主体

自定义令牌提供程序

先决条件

应用程序主体身份验证方法

本部分介绍使用应用程序主体进行身份验证的不同方法。

托管标识身份验证

有两种类型的托管标识:系统分配的托管标识和用户分配的托管标识。 系统分配的托管标识的生命周期与创建它们的资源相关联。 此身份仅限于一个资源。 而用户分配的托管标识可用于多个资源。 有关详细信息,请参阅 Managed Identities

在以下示例中,将 <QueryEndpointUri><ManagedIdentityClientId> 替换为您的值。

  • 系统分配的托管标识:

    var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
      .WithAadSystemManagedIdentity();
    
  • 用户分配的托管标识。 使用标识客户端 ID 或对象 ID,如下所示:

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

重要

  • 必须将托管标识资源的对象 ID 或主体 ID 分配一个角色以访问 Kusto 群集。 可以在 Kusto 群集资源页的 Azure portal 中,在 Security + networking>Permissions 下分配角色。 不应将托管标识直接附加到 Kusto 群集。
  • 本地开发环境中不支持托管标识身份验证。 若要测试托管标识身份验证,请将应用程序部署到Azure或在本地工作时使用不同的身份验证方法。

基于证书的身份验证

证书充当机密,用于在请求令牌时对应用程序标识进行身份验证。 有多种方法可以加载证书,例如从计算机的本地凭证存储或磁盘加载证书。

| 在以下示例中,将 <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)。 证书对象必须包含私钥:

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

    有关详细信息,请参阅 Kusto 连接字符串

重要

若要从Azure Key Vault加载证书,可以使用 Azure。Security.KeyVault.Certificatesclient

应用程序密钥身份验证

应用程序密钥也称为应用程序密码,是应用程序在请求获取令牌时用来进行身份验证和证明自身标识的机密字符串。 它充当应用程序access受保护资源的凭据形式。 应用程序密钥通常由标识提供者或授权服务器生成和分配。 请务必安全地管理和保护应用程序密钥,以防止未经授权访问敏感信息或执行操作。

| 在以下示例中,将 <QueryEndpointUri><ApplicationId><ApplicationKey><AuthorityId><AuthorityId> 替换为自己的值。

  • 应用程序密钥:

    var kcsb = new KustoConnectionStringBuilder(<QueryEndpointUri>)
      .WithAadApplicationKeyAuthentication(<ApplicationId>, <ApplicationKey>, <AuthorityId>);
    
  • 使用应用程序密钥的连接字符串:

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

重要

代码中的硬编码机密是错误的做法。 以纯文本形式存储敏感信息(如身份验证凭据)会导致安全漏洞。 加密敏感信息或将其安全地存储在key vault中。 使用加密或key vault可确保机密受到保护,并且仅可供授权用户或应用程序访问。

用户主体身份验证方法

本部分介绍使用用户主体进行身份验证的不同方法。

交互式用户登录身份验证

此身份验证方法使用用户的凭证与 Kusto 建立安全连接。 该方法将打开 Web 浏览器,提示用户输入其用户名和密码以完成身份验证过程。

| 在以下示例中,将 <QueryEndpointUri><AuthorityId><AuthorityId> 替换为自己的值。

  • 交互式用户登录:

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

Azure 命令行接口 (CLI)身份验证

此身份验证方法使用Azure Command-Line接口(CLI)对用户进行身份验证和获取令牌。 运行 az login 命令意味着用户可以安全地建立连接,并检索必要的令牌以进行身份验证。 如果令牌在Azure CLI缓存中不可用,并且 interactive 参数设置为 true,则可能会提示用户登录。 有关详细信息,请参阅 Azure Command-Line 接口 (CLI)

| 在以下示例中,将 <QueryEndpointUri> 替换为自己的值。

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

重要

.NET Framework 应用仅支持此方法。

设备代码身份验证

此方法适用于缺少用于登录的适当用户界面的设备,例如 IoT 设备和服务器终端。 它为用户提供使用其他设备(例如智能手机)进行身份验证的代码和 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;
  });

重要

可能会因为租户条件访问策略而阻止设备代码身份验证。 如果阻止,请选择备用身份验证方法。

自定义令牌提供程序身份验证方法

本部分介绍使用自定义令牌提供程序进行身份验证的不同方法。

用于联合托管标识凭证身份验证的自定义令牌提供程序

自定义令牌提供程序可用于获取用于身份验证的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.chinacloudapi.cn/.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();
    });

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

注意事项

DefaultAzureCredential用于对Azure服务进行身份验证。 它尝试使用多个身份验证方法来获取令牌,并且可以配置为使用托管标识、Visual Studio、Azure CLI等。 此凭证同时适用于测试和生产环境,因为它可以设置为使用不同的身份验证方法。 有关详细信息,请参阅 DefaultAzureCredential 类

下一步