Note

Access to this page requires authorization. You can try signing in or .

Access to this page requires authorization. You can try .

Integrate Azure Cosmos DB for Cassandra with Service Connector

This article shows supported authentication methods and clients, and provides sample code for connecting Azure Cosmos DB for Apache Cassandra to cloud services using Service Connector. You can also connect using other programming languages without Service Connector. The article includes default environment variable names and values you receive when creating a service connection.

Supported compute services

Service Connector can be used to connect the following compute services to Azure Cosmos DB for Apache Cassandra:

  • Azure App Service
  • Azure Functions
  • Azure Kubernetes Service (AKS)
  • Azure Spring Apps

Supported authentication types and client types

The table below shows which combinations of client types and authentication methods are supported for connecting your compute service to Azure Cosmos DB for Apache Cassandra using Service Connector. A “Yes” indicates that the combination is supported, while a “No” indicates that it is not supported.

Client type System-assigned managed identity User-assigned managed identity Secret / connection string Service principal
.NET Yes Yes Yes Yes
Go Yes Yes Yes Yes
Java Yes Yes Yes Yes
Java - Spring Boot No No Yes No
Node.js Yes Yes Yes Yes
Python Yes Yes Yes Yes
None Yes Yes Yes Yes

This table indicates that all combinations of client types and authentication methods in the table are supported, except for the Java - Spring Boot client type, which only supports the Secret / connection string method. All other client types can use any of the authentication methods to connect to Azure Cosmos DB for Apache Cassandra using Service Connector.

Note

Cosmos DB does not natively support authentication via managed identity. Therefore, Service Connector uses the managed identity to retrieve the connection string, and the connection is subsequently established using that connection string.

Default environment variable names or application properties and sample code

Reference the connection details and sample code in the following tables, according to your connection's authentication type and client type, to connect your compute services to Azure Cosmos DB for Apache Cassandra. For more information about naming conventions, check the Service Connector internals article.

System-assigned managed identity

Default environment variable name Description Example value
AZURE_COSMOS_LISTKEYURL The URL to get the connection string https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<Azure-Cosmos-DB-account>/listKeys?api-version=2021-04-15
AZURE_COSMOS_SCOPE Your managed identity scope https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT Your resource endpoint https://<Azure-Cosmos-DB-account>.documents.azure.com:443/
AZURE_COSMOS_CONTACTPOINT Azure Cosmos DB for Apache Cassandra contact point <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Cassandra connection port 10350
AZURE_COSMOS_KEYSPACE Cassandra keyspace <keyspace>
AZURE_COSMOS_USERNAME Cassandra username <username>

Sample code

Connect to Azure Cosmos DB for Cassandra using a system-assigned managed identity.

Since Cosmos DB doesn't natively support authentication via managed identity, in the following code sample, we use the managed identity to retrieve the connection string, and the connection is then established using that connection string.

  1. Install dependencies.

    dotnet add package CassandraCSharpDriver --version 3.19.3
    dotnet add package Azure.Identity
    
  2. Get an access token for the managed identity or service principal by using Azure.Identity. Use the access token and AZURE_COSMOS_LISTKEYURL to get the password. Then use connection information from environment variables added by Service Connector to connect to Azure Cosmos DB for Cassandra. In the code below, uncomment the section for your authentication type:

    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Net.Http;
    using System.Security.Authentication;
    using System.Security.Cryptography.X509Certificates;
    using System.Threading.Tasks;
    using Cassandra;
    using Azure.Identity;
    
    public class Program
    {
    	public static async Task Main()
    	{
     var cassandraContactPoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTACTPOINT");
     var userName = Environment.GetEnvironmentVariable("AZURE_COSMOS_USERNAME");
     var cassandraPort = Int32.Parse(Environment.GetEnvironmentVariable("AZURE_COSMOS_PORT"));
     var cassandraKeyspace = Environment.GetEnvironmentVariable("AZURE_COSMOS_KEYSPACE");
     var listKeyUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTKEYURL");
     var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
     // Uncomment the following lines corresponding to the authentication type you want to use.
     // For system-assigned identity.
     // var tokenProvider = new DefaultAzureCredential();
    
     // For user-assigned identity.
     // var tokenProvider = new DefaultAzureCredential(
     // new DefaultAzureCredentialOptions
     // {
     // ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
     // }
     // );
    
     // For service principal.
     // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
     // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
     // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
     // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);
    
     // Acquire the access token. 
     AccessToken accessToken = await tokenProvider.GetTokenAsync(
     new TokenRequestContext(scopes: new string[]{ scope }));
    
     // Get the password.
     var httpClient = new HttpClient();
     httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
     var response = await httpClient.POSTAsync(listKeyUrl);
     var responseBody = await response.Content.ReadAsStringAsync();
     var keys = JsonConvert.DeserializeObject<Dictionary<string, string>>(responseBody);
     var password = keys["primaryMasterKey"];
    
     // Connect to Azure Cosmos DB for Cassandra
     var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
     options.SetHostNameResolver((ipAddress) => cassandraContactPoint);
     Cluster cluster = Cluster
     .Builder()
     .WithCredentials(userName, password)
     .WithPort(cassandraPort)
     .AddContactPoint(cassandraContactPoint).WithSSL(options).Build();
     ISession session = await cluster.ConnectAsync();
     }
    
     public static bool ValidateServerCertificate
    	(
     object sender,
     X509Certificate certificate,
     X509Chain chain,
     SslPolicyErrors sslPolicyErrors
     )
     {
     if (sslPolicyErrors == SslPolicyErrors.None)
     return true;
    
     Console.WriteLine("Certificate error: {0}", sslPolicyErrors);
     // Do not allow this client to communicate with unauthenticated servers.
     return false;
     }
    }
    
    

User-assigned managed identity

Default environment variable name Description Example value
AZURE_COSMOS_LISTKEYURL The URL to get the connection string https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<Azure-Cosmos-DB-account>/listKeys?api-version=2021-04-15
AZURE_COSMOS_SCOPE Your managed identity scope https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT Your resource endpoint https://<Azure-Cosmos-DB-account>.documents.azure.com:443/
AZURE_COSMOS_CONTACTPOINT Azure Cosmos DB for Apache Cassandra contact point <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Cassandra connection port 10350
AZURE_COSMOS_KEYSPACE Cassandra keyspace <keyspace>
AZURE_COSMOS_USERNAME Cassandra username <username>
AZURE_COSMOS_CLIENTID Your client ID <client-ID>

Sample code

Connect to Azure Cosmos DB for Cassandra using a user-assigned managed identity.

Since Cosmos DB doesn't natively support authentication via managed identity, in the following code sample, we use the managed identity to retrieve the connection string, and the connection is then established using that connection string.

  1. Install dependencies.

    dotnet add package CassandraCSharpDriver --version 3.19.3
    dotnet add package Azure.Identity
    
  2. Get an access token for the managed identity or service principal by using Azure.Identity. Use the access token and AZURE_COSMOS_LISTKEYURL to get the password. Then use connection information from environment variables added by Service Connector to connect to Azure Cosmos DB for Cassandra. In the code below, uncomment the section for your authentication type:

    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Net.Http;
    using System.Security.Authentication;
    using System.Security.Cryptography.X509Certificates;
    using System.Threading.Tasks;
    using Cassandra;
    using Azure.Identity;
    
    public class Program
    {
    	public static async Task Main()
    	{
     var cassandraContactPoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTACTPOINT");
     var userName = Environment.GetEnvironmentVariable("AZURE_COSMOS_USERNAME");
     var cassandraPort = Int32.Parse(Environment.GetEnvironmentVariable("AZURE_COSMOS_PORT"));
     var cassandraKeyspace = Environment.GetEnvironmentVariable("AZURE_COSMOS_KEYSPACE");
     var listKeyUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTKEYURL");
     var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
     // Uncomment the following lines corresponding to the authentication type you want to use.
     // For system-assigned identity.
     // var tokenProvider = new DefaultAzureCredential();
    
     // For user-assigned identity.
     // var tokenProvider = new DefaultAzureCredential(
     // new DefaultAzureCredentialOptions
     // {
     // ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
     // }
     // );
    
     // For service principal.
     // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
     // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
     // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
     // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);
    
     // Acquire the access token. 
     AccessToken accessToken = await tokenProvider.GetTokenAsync(
     new TokenRequestContext(scopes: new string[]{ scope }));
    
     // Get the password.
     var httpClient = new HttpClient();
     httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
     var response = await httpClient.POSTAsync(listKeyUrl);
     var responseBody = await response.Content.ReadAsStringAsync();
     var keys = JsonConvert.DeserializeObject<Dictionary<string, string>>(responseBody);
     var password = keys["primaryMasterKey"];
    
     // Connect to Azure Cosmos DB for Cassandra
     var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
     options.SetHostNameResolver((ipAddress) => cassandraContactPoint);
     Cluster cluster = Cluster
     .Builder()
     .WithCredentials(userName, password)
     .WithPort(cassandraPort)
     .AddContactPoint(cassandraContactPoint).WithSSL(options).Build();
     ISession session = await cluster.ConnectAsync();
     }
    
     public static bool ValidateServerCertificate
    	(
     object sender,
     X509Certificate certificate,
     X509Chain chain,
     SslPolicyErrors sslPolicyErrors
     )
     {
     if (sslPolicyErrors == SslPolicyErrors.None)
     return true;
    
     Console.WriteLine("Certificate error: {0}", sslPolicyErrors);
     // Do not allow this client to communicate with unauthenticated servers.
     return false;
     }
    }
    
    

Connection string

Warning

Microsoft recommends that you use the most secure authentication flow available. The authentication flow described in this procedure requires a very high degree of trust in the application, and carries risks that are not present in other flows. You should only use this flow when other more secure flows, such as managed identities, aren't viable.

Spring Boot client type

Default environment variable name Description Example value
spring.data.cassandra.contact-points Azure Cosmos DB for Apache Cassandra contact point <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
spring.data.cassandra.port Cassandra connection port 10350
spring.data.cassandra.keyspace-name Cassandra keyspace <keyspace>
spring.data.cassandra.username Cassandra username <username>
spring.data.cassandra.password Cassandra password <password>
spring.data.cassandra.local-datacenter Azure Region <Azure-region>
spring.data.cassandra.ssl SSL status true

Other client types

Default environment variable name Description Example value
AZURE_COSMOS_CONTACTPOINT Azure Cosmos DB for Apache Cassandra contact point <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Cassandra connection port 10350
AZURE_COSMOS_KEYSPACE Cassandra keyspace <keyspace>
AZURE_COSMOS_USERNAME Cassandra username <username>
AZURE_COSMOS_PASSWORD Cassandra password <password>

Sample code

To connect using a connection string:

  1. Install dependency.

    dotnet add package CassandraCSharpDriver --version 3.19.3
    
  2. Get the connection information from the environment variables added by Service Connector and connect to Azure Cosmos DB for Cassandra.

    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Security.Authentication;
    using System.Security.Cryptography.X509Certificates;
    using System.Threading.Tasks;
    using Cassandra;
    
    public class Program
    {
    	public static async Task Main()
    	{
     var cassandraContactPoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTACTPOINT");
     var userName = Environment.GetEnvironmentVariable("AZURE_COSMOS_USERNAME");
     var password = Environment.GetEnvironmentVariable("AZURE_COSMOS_PASSWORD");
     var cassandraPort = Int32.Parse(Environment.GetEnvironmentVariable("AZURE_COSMOS_PORT"));
     var cassandraKeyspace = Environment.GetEnvironmentVariable("AZURE_COSMOS_KEYSPACE");
    
     var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
     options.SetHostNameResolver((ipAddress) => cassandraContactPoint);
     Cluster cluster = Cluster
     .Builder()
     .WithCredentials(userName, password)
     .WithPort(cassandraPort)
     .AddContactPoint(cassandraContactPoint).WithSSL(options).Build();
     ISession session = await cluster.ConnectAsync();
     }
    
     public static bool ValidateServerCertificate
    	(
     object sender,
     X509Certificate certificate,
     X509Chain chain,
     SslPolicyErrors sslPolicyErrors
     )
     {
     if (sslPolicyErrors == SslPolicyErrors.None)
     return true;
    
     Console.WriteLine("Certificate error: {0}", sslPolicyErrors);
     // Do not allow this client to communicate with unauthenticated servers.
     return false;
     }
    }
    
    

For more information, see Build an Apache Cassandra app with .NET SDK and Azure Cosmos DB.

Service principal

Default environment variable name Description Example value
AZURE_COSMOS_LISTKEYURL The URL to get the connection string https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<Azure-Cosmos-DB-account>/listKeys?api-version=2021-04-15
AZURE_COSMOS_SCOPE Your managed identity scope https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT Your resource endpoint https://<Azure-Cosmos-DB-account>.documents.azure.com:443/
AZURE_COSMOS_CONTACTPOINT Azure Cosmos DB for Apache Cassandra contact point <Azure-Cosmos-DB-account>.cassandra.cosmos.azure.com
AZURE_COSMOS_PORT Cassandra connection port 10350
AZURE_COSMOS_KEYSPACE Cassandra keyspace <keyspace>
AZURE_COSMOS_USERNAME Cassandra username <username>
AZURE_COSMOS_CLIENTID Your client ID <client-ID>
AZURE_COSMOS_CLIENTSECRET Your client secret <client-secret>
AZURE_COSMOS_TENANTID Your tenant ID <tenant-ID>

Sample code

To connect using a service principal:

  1. Install dependencies.

    dotnet add package CassandraCSharpDriver --version 3.19.3
    dotnet add package Azure.Identity
    
  2. Get an access token for the managed identity or service principal by using Azure.Identity. Use the access token and AZURE_COSMOS_LISTKEYURL to get the password. Then use connection information from environment variables added by Service Connector to connect to Azure Cosmos DB for Cassandra. In the code below, uncomment the section for your authentication type:

    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Net.Http;
    using System.Security.Authentication;
    using System.Security.Cryptography.X509Certificates;
    using System.Threading.Tasks;
    using Cassandra;
    using Azure.Identity;
    
    public class Program
    {
    	public static async Task Main()
    	{
     var cassandraContactPoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTACTPOINT");
     var userName = Environment.GetEnvironmentVariable("AZURE_COSMOS_USERNAME");
     var cassandraPort = Int32.Parse(Environment.GetEnvironmentVariable("AZURE_COSMOS_PORT"));
     var cassandraKeyspace = Environment.GetEnvironmentVariable("AZURE_COSMOS_KEYSPACE");
     var listKeyUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTKEYURL");
     var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
     // Uncomment the following lines corresponding to the authentication type you want to use.
     // For system-assigned identity.
     // var tokenProvider = new DefaultAzureCredential();
    
     // For user-assigned identity.
     // var tokenProvider = new DefaultAzureCredential(
     // new DefaultAzureCredentialOptions
     // {
     // ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
     // }
     // );
    
     // For service principal.
     // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
     // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
     // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
     // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);
    
     // Acquire the access token. 
     AccessToken accessToken = await tokenProvider.GetTokenAsync(
     new TokenRequestContext(scopes: new string[]{ scope }));
    
     // Get the password.
     var httpClient = new HttpClient();
     httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
     var response = await httpClient.POSTAsync(listKeyUrl);
     var responseBody = await response.Content.ReadAsStringAsync();
     var keys = JsonConvert.DeserializeObject<Dictionary<string, string>>(responseBody);
     var password = keys["primaryMasterKey"];
    
     // Connect to Azure Cosmos DB for Cassandra
     var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
     options.SetHostNameResolver((ipAddress) => cassandraContactPoint);
     Cluster cluster = Cluster
     .Builder()
     .WithCredentials(userName, password)
     .WithPort(cassandraPort)
     .AddContactPoint(cassandraContactPoint).WithSSL(options).Build();
     ISession session = await cluster.ConnectAsync();
     }
    
     public static bool ValidateServerCertificate
    	(
     object sender,
     X509Certificate certificate,
     X509Chain chain,
     SslPolicyErrors sslPolicyErrors
     )
     {
     if (sslPolicyErrors == SslPolicyErrors.None)
     return true;
    
     Console.WriteLine("Certificate error: {0}", sslPolicyErrors);
     // Do not allow this client to communicate with unauthenticated servers.
     return false;
     }
    }
    
    

Next steps

Follow the tutorials listed below to learn more about Service Connector.


Feedback

Was this page helpful?

Additional resources