Строки подключения Azure Data Explorer

Строки подключения могут предоставлять клиентскому приложению Data Explorer необходимые сведения для подключения к конечной точке службы Data Explorer. Эти строки подключения смоделированы на основе аналогичных строк ADO.NET, то есть они представляют собой список пар параметров "имя-значение" через точку с запятой, перед которыми может указываться один универсальный код ресурса (URI).

Пример.

https://help.kusto.windows.net/Samples; Fed=true; Accept=true

Код URI предоставляет конечную точку службы для взаимодействия:

  • (https://help.kusto.windows.net) — значение свойства Data Source.
  • Samples (база данных по умолчанию) — значение свойства Initial Catalog.

Синтаксис имени-значения предоставляет два дополнительных свойства:

  • Свойство Fed (также называемое AAD Federated Security) имеет значение true.
  • Свойство Accept имеет значение true.

Примечание

  • Регистр в именах свойств не учитывается, а пробелы между парами имя-значение игнорируются.
  • Значения свойств задаются с учетом регистра. Значение свойства, содержащее точку с запятой (;), одинарную кавычку (') или двойную кавычку ("), должно помещаться внутри двойных кавычек.

Несколько клиентских средств Kusto поддерживают расширение по префиксу URI строки подключения, в котором они позволяют использовать сокращенный формат @@// . Например, строка подключения @help/Samples преобразуется этими инструментами в строку https://help.kusto.windows.net/Samples; Fed=true, которая задает три свойства: Data Source, Initial Catalog и AAD Federated Security.

В программном коде строки подключения Data Explorer можно анализировать и изменять на языке C# при помощи класса Kusto.Data.KustoConnectionStringBuilder. Этот класс проверяет все строки подключения, и при сбое проверки выдает исключение во время выполнения. Такие функции присутствуют во всех вариантах пакета SDK для Kusto.

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

В следующей таблице перечислены все свойства, которые можно указать в строке подключения Data Explorer. Здесь приведены имена в программном коде (имена свойств в объекте Kusto.Data.KustoConnectionStringBuilder), а также дополнительные имена-псевдонимы.

Общие свойства

Имя свойства Альтернативные имена Имя в программном коде Описание
Версия клиента для трассировки TraceClientVersion Используйте это значение при трассировке версии клиента.
Источник данных Addr, Address (адрес), Network Address (сетевой адрес), Server (сервер) DataSource Код URI для указания конечной точки службы Data Explorer. Например, https://mycluster.kusto.windows.net или net.tcp://localhost.
Начальный каталог Database (база данных) InitialCatalog Имя базы данных, используемой по умолчанию, например MyDatabase.
Согласованность запроса QueryConsistency QueryConsistency Задайте значение strongconsistency либо weakconsistency, чтобы указать, должен ли запрос синхронизироваться с метаданными перед выполнением.

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

Имя свойства Альтернативные имена Имя в программном коде Описание
Федеративная безопасность AAD Federated Security, Federated, Fed, AADFed FederatedSecurity Логическое значение, которое указывает клиенту применять Azure Active.
Принудительное применение MFA MFA, EnforceMFA EnforceMfa Логическое значение, указывающее, что клиент должен получить маркер многофакторной проверки подлинности.
ИД пользователя UID, User (пользователь) UserID Строковое значение, которое указывает клиенту выполнить проверку подлинности пользователя с заданным именем.
Имя пользователя для трассировки TraceUserName Строковое значение, которое сообщает службе, какое имя пользователя применять при внутренней трассировке запроса.
Маркер пользователя UsrToken, UserToken UserToken Строковое значение, которое указывает клиенту выполнить проверку подлинности пользователя с заданным маркером носителя.
Это свойство переопределяет ApplicationClientId, ApplicationKey и ApplicationToken. (Если оно указано, то фактический клиентский поток проверки подлинности будет пропущен и будет использован предоставленный маркер.)
Пространство имен NS Namespace (Для использования в будущем.)

Свойства проверки подлинности приложения

Имя свойства Альтернативные имена Имя в программном коде Описание
Федеративная безопасность AAD Federated Security, Federated, Fed, AADFed FederatedSecurity Логическое значение, которое указывает клиенту применять федеративную проверку подлинности Azure Active Directory (AAD).
Отпечаток сертификата приложения AppCert ApplicationCertificateThumbprint Строковое значение, предоставляющее отпечаток сертификата клиента для использования в соответствующем потоке проверки подлинности приложения.
ИД клиента приложения AppClientId ApplicationClientId Строковое значение, которое предоставляет идентификатор клиента приложения для использования при проверке подлинности.
Ключ приложения AppKey ApplicationKey Строковое значение, которое предоставляет ключ приложения для использования в потоке проверки подлинности на основе секрета приложения.
Имя приложения для трассировки TraceAppName ApplicationNameForTracing Строковое значение, которое сообщает службе, какое имя приложения применять при внутренней трассировке запроса.
Маркер приложения AppToken ApplicationToken Строковое значение, которое указывает клиенту выполнить проверку подлинности приложения с заданным маркером носителя.
ИД центра регистрации TenantId (ИД клиента) Authority Строковое значение, предоставляющее имя или идентификатор клиента, в котором зарегистрировано приложение.
Управляемое удостоверение службы Недоступно EmbeddedManagedIdentity Строковое значение, которое указывает клиенту, какое удостоверение приложения применять для проверки подлинности с использованием управляемого удостоверения. Укажите значение system, чтобы использовать удостоверение, назначаемое системой. Это свойство не указывается в строке подключения, его можно задать только программно.
Различающееся имя субъекта сертификата приложения Application Certificate Subject (субъект сертификата приложения) ApplicationCertificateSubjectDistinguishedName
Различающееся имя издателя сертификата приложения Application Certificate Issuer (издатель сертификата приложения) ApplicationCertificateIssuerDistinguishedName
Общедоступный сертификат для отправки сертификата приложения Application Certificate SendX5c, SendX5c ApplicationCertificateSendPublicCertificate

Свойства взаимодействия с клиентом

Имя свойства Альтернативные имена Имя в программном коде Описание
Принятие Accept Логическое значение, которое запрашивает объекты с подробными сведениями об ошибках для возврата в случае сбоя.
Потоковая передача Streaming Логическое значение, которое запрашивает, чтобы клиент не накапливал данные перед предоставлением их вызывающему объекту.
Без сжатия Uncompressed Логическое значение, которое запрашивает, чтобы клиент не требовал сжатия на транспортном уровне.

Свойства проверки подлинности (подробности)

Одной из важных задач строки подключения является указание клиенту, как выполнять проверку подлинности в службе. Для проверки подлинности на конечных точках HTTP/HTTPS клиенты обычно используют следующий алгоритм.

  1. Если AadFederatedSecurity имеет значение true:

    1. Если указано свойство UserToken, используется федеративная проверка подлинности AAD с заданным маркером.
    2. Если указано свойство ApplicationToken, выполняется федеративная проверка подлинности с заданным маркером.
    3. Если указаны свойства ApplicationClientId и ApplicationKey, выполняется федеративная проверка подлинности с заданными ИД клиента и ключом приложения.
    4. Если указаны свойства ApplicationClientId и ApplicationCertificateThumbprint, выполняется федеративная проверка подлинности с заданными ИД клиента и сертификатом приложения.
    5. В прочих случаях выполняется федеративная проверка подлинности на базе удостоверения пользователя, зарегистрированного сейчас в системе (пользователь получит соответствующий запрос, если это первая проверка подлинности в сеансе).
  2. В противном случае проверка подлинности не выполняется.

Федеративная проверка подлинности AAD для приложения с сертификатом

  1. Проверка подлинности на основе сертификата поддерживается только для веб-приложений (не для приложений на платформе клиента).
  2. Веб-приложение должно быть настроено на прием данного сертификата. Практическое руководство по проверке подлинности на основе сертификата приложения AAD
  3. Веб-приложение должно быть настроено как полномочный субъект в соответствующем кластере Data Explorer.
  4. Требуется установка сертификата с заданным отпечатком (в хранилище локального компьютера или текущего пользователя).
  5. Открытый ключ сертификата должен содержать не менее 2048 бит.

Примеры проверки подлинности на базе AAD

Федеративная проверка подлинности AAD на базе удостоверения пользователя, зарегистрированного сейчас в системе (при необходимости пользователь получит соответствующий запрос)

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
  .WithAadUserPromptAuthentication(authority);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    InitialCatalog = "NetDefaultDB",
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;Authority Id={authority}"

Федеративная проверка подлинности AAD с указанием ИД пользователя (при необходимости пользователь получит соответствующий запрос)

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
var userUPN = "johndoe@contoso.com";

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
  .WithAadUserPromptAuthentication(authority);
kustoConnectionStringBuilder.UserID = userUPN;

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    InitialCatalog = "NetDefaultDB",
    UserID = userUPN,
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;User ID={userUPN};Authority Id={authority}"

Федеративная проверка подлинности AAD с использованием ApplicationClientId и ApplicationKey

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
var applicationClientId = <ApplicationClientId>;
var applicationKey = <ApplicationKey>;

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadApplicationKeyAuthentication(applicationClientId, applicationKey, authority);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    InitialCatalog = "NetDefaultDB",
    ApplicationClientId = applicationClientId,
    ApplicationKey = applicationKey,
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;AppClientId={applicationClientId};AppKey={applicationKey};Authority Id={authority}"

Использование управляемого удостоверения, назначаемого системой

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadSystemManagedIdentity();

Использование управляемого удостоверения, назначаемого пользователем

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
var managedIdentityClientId = "<managed identity client id>";

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadUserManagedIdentity(managedIdentityClientId);

Федеративная проверка подлинности AAD с применением маркера пользователя/приложения

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
var access_token = "<access token obtained from AAD>"

// Recommended syntax - AAD User token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadUserTokenAuthentication(access_token, authority);

// Legacy syntax - AAD User token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    UserToken = access_token,
    Authority = authority,
};

// Equivalent Kusto connection string: "Data Source={serviceUri};Database=NetDefaultDB;Fed=True;UserToken={access_token};Authority Id={authority}"

// Recommended syntax - AAD Application token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadApplicationTokenAuthentication(access_token, authority);

// Legacy syntax - AAD Application token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    ApplicationToken = access_token,
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;AppToken={applicationToken};Authority Id={authority}"

Использование обратного вызова поставщика маркера (вызов при каждом требовании маркера)

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadTokenProviderAuthentication(tokenProviderCallback);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    TokenProviderCallback = () => Task.FromResult(tokenProviderCallback()),
};

Использование сертификата X.509

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
string applicationClientId = "<applicationClientId>";
X509Certificate2 applicationCertificate = "<certificate blob>";
bool sendX5c = <desired value>; // Set too 'True' to use Trusted Issuer feature of AAD

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadApplicationCertificateAuthentication(applicationClientId, applicationCertificate, authority, sendX5c);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    ApplicationClientId = applicationClientId,
    ApplicationCertificateBlob = applicationCertificate,
    ApplicationCertificateSendX5c = sendX5c,
    Authority = authority,
};

Использование сертификата X.509 по опечатку (клиент будет пытаться загрузить сертификат из локального хранилища)

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
string applicationClientId = "<applicationClientId>";
string applicationCertificateThumbprint = "<ApplicationCertificateThumbprint>";

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadApplicationThumbprintAuthentication(applicationClientId, applicationCertificateThumbprint, authority);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    ApplicationClientId = applicationClientId,
    ApplicationCertificateThumbprint = applicationCertificateThumbprint,
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;AppClientId={applicationClientId};AppCert={applicationCertificateThumbprint};Authority Id={authority}"