Kusto connection strings

Applies to: ✅ Microsoft Fabric ✅ Azure Data Explorer

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.

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 environment.
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 = "serviceURI";
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 = "serviceURI";
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 = "serviceURI";
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}"

Microsoft Entra ID Federated authentication using user / application token

var kustoUri = "serviceURI";
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 = "serviceURI";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadTokenProviderAuthentication(tokenProviderCallback);

Using X.509 certificate

var kustoUri = "serviceURI";
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 = "serviceURI";
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}"