Edit

Kusto connection strings

  • Article

Kusto connection strings provide the information necessary for a Kusto client application to establish a connection to a Kusto service endpoint. Kusto connection strings are modeled after the ADO.NET connection strings. That is, the connection string is a semicolon-delimited list of name-value parameter pairs, optionally prefixed by a single URI.

For example, the following Kusto connection string begins with a URI that specifies the service endpoint for communication: https://help.kusto.windows.net. This URI is assigned to the Data Source property. Next, /Samples within the connection string represents the default database and is assigned to the Initial Catalog property. Lastly, two other properties, Fed and Accept, provide further configuration or customization options for the connection.

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

Note

  • Property names are not case sensitive.
  • Property values are case sensitive.
  • Spaces between name-value parameter pairs are ignored.
  • A property value that contains a semicolon (;), a single quotation mark ('), or a double quotation mark (") must be enclosed between double quotation marks.

Several Kusto client tools support an extension over the URI prefix of the connection string that allows for a shorthand format of @ClusterName/InitialCatalog. For example, these tools translate the connection string @help/Samples to https://help.kusto.windows.net/Samples; Fed=true.

Programmatically, the C# Kusto.Data.KustoConnectionStringBuilder class can parse and manipulate Kusto connection strings. This class validates all connection strings and generates a runtime exception if validation fails. This functionality is present in all flavors of Kusto SDK.

Trusted endpoints

A connection with a Kusto endpoint can only be established if that endpoint is trusted. The Kusto client trusts all endpoints whose hostname part is issued by the service. For instance, endpoints whose DNS hostname ends with kusto.windows.net.

By default, the client doesn't establish connections to other endpoints. In order to allow connections to other endpoints, use the Kusto.Data.Common.KustoTrustedEndpoints class to add endpoints to the list of trusted endpoints. Use SetOverridePolicy to override the default policy, and AddTrustedHosts to add new entries to the existing policy.

KustoTrustedEndpoints.AddTrustedHosts(
    new[]
    {
        // Allow an explicit service address
        new FastSuffixMatcher.MatchRule("my-kusto.contoso.com", exact: true),
        // Allow services whose DNS name end with ".contoso.com"
        new FastSuffixMatcher.MatchRule(".contoso.com", exact: false),
    }
);

Connection string properties

The following tables list all the possible properties that can be included in a Kusto connection string. The tables also provide alias names for each property. Moreover, the tables indicate the programmatic names associated with each property, which represents the name of the property in the Kusto.Data.KustoConnectionStringBuilder object.

General properties

Property name Programmatic name Description
Client Version for Tracing TraceClientVersion When tracing the client version, use this property.
Data Source

Aliases: Addr, Address, Network Address, Server		 DataSource The URI specifying the Kusto service endpoint. For example, https://mycluster.kusto.windows.net.
Initial Catalog

Alias: Database		 InitialCatalog The name of the database to be used by default. For example, MyDatabase.
Query Consistency

Alias: QueryConsistency		 QueryConsistency Set to either strongconsistency or weakconsistency to determine if the query should synchronize with the metadata before running.

User authentication properties

Property name Programmatic name Description
Microsoft Entra ID Federated Security

Aliases: Federated Security, Federated, Fed, AADFed		 FederatedSecurity A boolean value that instructs the client to perform Microsoft Entra authentication.
Authority ID

Alias: TenantId		 Authority A string value that provides the name or ID of the user's tenant. The default value is microsoft.com. For more information, see Microsoft Entra authority.
Enforce MFA

Alias: MFA, EnforceMFA		 EnforceMfa An optional boolean value that instructs the client to acquire a multifactor-authentication token.
User ID

Aliases: UID, User		 UserID A string value that instructs the client to perform user authentication with the indicated user name.
User Name for Tracing TraceUserName An optional string value that reports to the service which user name to use when tracing the request internally.
User Token

Aliases: UsrToken, UserToken		 UserToken A string value that instructs the client to perform user authentication with the specified bearer token.

Overrides ApplicationClientId, ApplicationKey, and ApplicationToken. If specified, skips the actual client authentication flow in favor of the provided token.

Supported property combinations for user authentication

For user authentication, specify AAD Federated Security as true. Then, choose one of the following authentication modes, and specify the relevant properties for that mode.

Authentication mode Property names
Microsoft Entra user Prompt Authentication - User ID (optional)
- Authority ID (optional)
- Enforce MFA (optional)
- User Name for Tracing (optional)
Microsoft Entra user Token Authentication - User Token
- Enforce MFA (optional)
- User Name for Tracing (optional)

Application authentication properties

Property name Programmatic name Description
Microsoft Entra ID Federated Security

Aliases: Federated Security, Federated, Fed, AADFed		 FederatedSecurity A boolean value that instructs the client to perform Microsoft Entra ID federated authentication.
Application Certificate SendX5c

Aliases: Application Certificate Send Public Certificate, SendX5c		 ApplicationCertificateSendX5c A boolean value that instructs the client to perform subject name and issuer based authentication.
Application Certificate Thumbprint

Alias: AppCert		 ApplicationCertificateThumbprint A string value that provides the thumbprint of the client certificate to use when using an application client certificate authenticating flow.
Application Client ID

Alias: AppClientId		 ApplicationClientId A string value that provides the application client ID to use when authenticating.
Application Key

Alias: AppKey		 ApplicationKey A string value that provides the application key to use when authenticating using an application secret flow.
Application Name for Tracing

Alias: TraceAppName		 ApplicationNameForTracing An optional string value that reports to the service which application name to use when tracing the request internally.
Application Token

Alias: AppToken		 ApplicationToken A string value that instructs the client to perform application authenticating with the specified bearer token.
Authority ID

Alias: TenantId		 Authority A string value that provides the name or ID of the tenant in which the application is registered. The default value is microsoft.com. For more information, see Microsoft Entra authority.
Azure Region

Aliases: AzureRegion, Region		 AzureRegion A string value that provides the name of the Azure Region in which to authenticate.
ManagedServiceIdentity EmbeddedManagedIdentity A string value that instructs the client which application identity to use with managed identity authentication. Use system to indicate the system-assigned identity.

This property can't be set with a connection string, only programmatically.
Application Certificate Subject Distinguished Name

Alias: Application Certificate Subject		 ApplicationCertificateSubjectDistinguishedName A string value that specifies the application certificate subject distinguished name.
Application Certificate Issuer Distinguished Name

Alias: Application Certificate Issuer		 ApplicationCertificateIssuerDistinguishedName A string value that specifies the application certificate issuer distinguished name.

Supported property combinations for application authentication

For application authentication, specify AAD Federated Security as true. Then, choose one of the following authentication modes, and specify the relevant properties for that mode.

Authentication mode Property names
Microsoft Entra Application Key Authentication - Application Client Id
- Application Key
- Authority Id
- Application Name for Tracing (optional)
Microsoft Entra Application Thumbprint Authentication - Application Client Id
- Application Certificate Thumbprint
- Authority Id
- Application Name for Tracing (optional)
Microsoft Entra Application Subject and Issuer Authentication - Application Client Id
- Application Certificate Subject Distinguished Name
- Application Certificate Issuer Distinguished Name
- Authority Id
- Azure Region (optional)
- Application Certificate SendX5c (optional)
- Application Name for Tracing (optional)
Microsoft Entra Application Subject Name Authentication - Application Client Id
- Application Certificate Subject Distinguished Name
- Authority Id
- and Azure Region (optional)
- Application Name for Tracing (optional)
Microsoft Entra Application Token Authentication - Application Token
- Application Name for Tracing (optional)

Authentication with an application certificate

  1. The application should be configured to accept the given certificate. How to authentication based-on Microsoft Entra application's certificate.
  2. The application should be configured as an authorized principal in the relevant Kusto cluster.
  3. The certificate needs to be installed in Local Machine store or in Current User store.
  4. The certificate's public key should contain at least 2048 bits.

Client communication properties

Property name Programmatic name Description
Accept Accept A boolean value that requests detailed error objects to be returned on failure.
Streaming Streaming A boolean value that requests the client not accumulate data before providing it to the caller. This is a default behavior.
Uncompressed Uncompressed A boolean value that requests the client not ask for transport-level compression.

Note

When the Streaming flag is enabled (as is the default), the SDK does not buffer all response data in memory; instead, it "pulls" the data from the service when the caller requests it. Therefore, it is essential that in this case the caller properly disposes of the data (such as IDataReader) once it is done reading the data, as the network connection to the service is held open unnecessarily.

Examples

Microsoft Entra ID Federated authentication using the currently logged-on user identity (user will be prompted if required)

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadUserPromptAuthentication(authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;Authority Id={authority}"

Microsoft Entra ID Federated authentication with user id hint (user will be prompted if required)

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID
var userId = "johndoe@contoso.com";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
  .WithAadUserPromptAuthentication(authority, userId);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;Authority Id={authority};User ID={userId}"

Microsoft Entra ID Federated application authentication using ApplicationClientId and ApplicationKey

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var appId = "<appId>";
var appKey = "<appKey>";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadApplicationKeyAuthentication(appId, appKey, authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;AppClientId={appId};AppKey={appKey};Authority Id={authority}"

Using System-assigned Managed Identity

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadSystemManagedIdentity();

Using User-assigned Managed Identity

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadUserManagedIdentity(managedIdentityClientId);

Microsoft Entra ID Federated authentication using user / application token

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var userAccessToken = "<userAccessToken>";
var appAccessToken = "<appAccessToken>";
// AAD User token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadUserTokenAuthentication(userAccessToken);
    
// Equivalent Kusto connection string: "Data Source={kustoUri};Database=NetDefaultDB;Fed=True;UserToken={userAccessToken}"
// AAD Application token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadApplicationTokenAuthentication(appAccessToken);
    
// Equivalent Kusto connection string: "Data Source={kustoUri};Database=NetDefaultDB;Fed=True;ApplicationToken={appAccessToken}"

Using token provider callback (will be invoked each time a token is required)

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadTokenProviderAuthentication(tokenProviderCallback);

Using X.509 certificate

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var appId = "<appId>";
X509Certificate2 appCert;
var authority = "contoso.com"; // Or the AAD tenant GUID
bool sendX5c; // Set to 'True' to use Trusted Issuer feature of AAD
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadApplicationCertificateAuthentication(appId, appCert, authority, sendX5c);

Using X.509 certificate by thumbprint (client will attempt to load the certificate from local store)

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var appId = "<appId>";
var appCert = "<appCert>";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadApplicationThumbprintAuthentication(appId, appCert, authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;AppClientId={appId};AppCert={appCert};Authority Id={authority}"