Integrate Azure Cosmos DB for MongoDB with Service Connector

This page shows supported authentication methods and clients, and shows sample code you can use to connect the Azure Cosmos DB for MongoDB to other cloud services using Service Connector. You might still be able to connect to Azure Cosmos DB for MongoDB in other programming languages without using Service Connector. This page also shows default environment variable names and values (or Spring Boot configuration) you get when you create the service connection.

Supported compute services

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

  • Azure App Service
  • Azure Functions
  • Azure Container Apps
  • 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 MongoDB 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
Java Yes Yes Yes Yes
Java - Spring Boot No No Yes No
Node.js Yes Yes Yes Yes
Python Yes Yes Yes Yes
Go 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 MongoDB using Service Connector.

Default environment variable names or application properties and sample code

Use the connection details below to connect compute services to Azure Cosmos DB. This page also shows default environment variable names and values (or Spring Boot configuration) you get when you create the service connection, as well as sample code. For each example below, replace the placeholder texts <mongo-db-admin-user>, <password>, <Azure-Cosmos-DB-API-for-MongoDB-account>, <subscription-ID>, <resource-group-name>, <client-secret>, and <tenant-id> with your own information. 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_LISTCONNECTIONSTRINGURL 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-API-for-MongoDB-account>/listConnectionStrings?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-API-for-MongoDB-account>.documents.azure.com:443/

Sample code

Refer to the steps and code below to connect to Azure Cosmos DB for MongoDB using a system-assigned managed identity.

  1. Install dependencies

    dotnet add package MongoDb.Driver
    dotnet add package Azure.Identity
    
  2. Get an access token for the managed identity or service principal using client library Azure.Identity. Use the access token and AZURE_COSMOS_LISTCONNECTIONSTRINGURL to get the connection string. Get the connection information from the environment variables added by Service Connector and connect to Azure Cosmos DB for MongoDB. When using the code below, uncomment the part of the code snippet for the authentication type you want to use.

    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 MongoDB.Driver;
    using Azure.Identity;
    using System.Text.Json;
    
    var endpoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
    var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
    // Uncomment the following lines according to the authentication type.
    // 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 connection string.
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
    var response = await httpClient.POSTAsync(listConnectionStringUrl);
    var responseBody = await response.Content.ReadAsStringAsync();
    var connectionStrings = JsonSerializer.Deserialize<Dictionary<string, List<Dictionary<string, string>>>>(responseBody);
    string connectionString = connectionStrings["connectionStrings"][0]["connectionString"];
    
    // Connect to Azure Cosmos DB for MongoDB
    var client = new MongoClient(connectionString);
    

User-assigned managed identity

Default environment variable name Description Example value
AZURE_COSMOS_LISTCONNECTIONSTRINGURL 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-API-for-MongoDB-account>/listConnectionStrings?api-version=2021-04-15
AZURE_COSMOS_SCOPE Your managed identity scope https://management.azure.com/.default
AZURE_COSMOS_CLIENTID Your client ID <client-ID>
AZURE_COSMOS_RESOURCEENDPOINT Your resource endpoint https://<Azure-Cosmos-DB-API-for-MongoDB-account>.documents.azure.com:443/

Sample code

Refer to the steps and code below to connect to Azure Cosmos DB for MongoDB using a user-assigned managed identity.

  1. Install dependencies

    dotnet add package MongoDb.Driver
    dotnet add package Azure.Identity
    
  2. Get an access token for the managed identity or service principal using client library Azure.Identity. Use the access token and AZURE_COSMOS_LISTCONNECTIONSTRINGURL to get the connection string. Get the connection information from the environment variables added by Service Connector and connect to Azure Cosmos DB for MongoDB. When using the code below, uncomment the part of the code snippet for the authentication type you want to use.

    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 MongoDB.Driver;
    using Azure.Identity;
    using System.Text.Json;
    
    var endpoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
    var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
    // Uncomment the following lines according to the authentication type.
    // 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 connection string.
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
    var response = await httpClient.POSTAsync(listConnectionStringUrl);
    var responseBody = await response.Content.ReadAsStringAsync();
    var connectionStrings = JsonSerializer.Deserialize<Dictionary<string, List<Dictionary<string, string>>>>(responseBody);
    string connectionString = connectionStrings["connectionStrings"][0]["connectionString"];
    
    // Connect to Azure Cosmos DB for MongoDB
    var client = new MongoClient(connectionString);
    

Connection string

SpringBoot client type

Default environment variable name Description Example value
spring.data.mongodb.database Your database <database-name>
spring.data.mongodb.uri Your database URI mongodb://<mongo-db-admin-user>:<password>@<mongo-db-server>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<mongo-db-server>@

Other client types

Default environment variable name Description Example value
AZURE_COSMOS_CONNECTIONSTRING MongoDB API connection string mongodb://<mongo-db-admin-user>:<password>@<mongo-db-server>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<mongo-db-server>@

Sample code

Refer to the steps and code below to connect to Azure Cosmos DB for MongoDB using a connection string.

  1. Install dependency.

    dotnet add package MongoDb.Driver
    
  2. Get the connection string from the environment variable added by Service Connector and connect to Azure Cosmos DB for MongoDB.

    using MongoDB.Driver;
    
    var connectionString = Environment.GetEnvironmentVariable("AZURE_COSMOS_CONNECTIONSTRING");
    var client = new MongoClient(connectionString);
    

Service principal

Default environment variable name Description Example value
AZURE_COSMOS_LISTCONNECTIONSTRINGURL 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-API-for-MongoDB-account>/listConnectionStrings?api-version=2021-04-15
AZURE_COSMOS_SCOPE Your managed identity scope https://management.azure.com/.default
AZURE_COSMOS_CLIENTID Your client ID <client-ID>
AZURE_COSMOS_CLIENTSECRET Your client secret <client-secret>
AZURE_COSMOS_TENANTID Your tenant ID <tenant-ID>
AZURE_COSMOS_RESOURCEENDPOINT Your resource endpoint https://<Azure-Cosmos-DB-API-for-MongoDB-account>.documents.azure.com:443/

Sample code

Refer to the steps and code below to connect to Azure Cosmos DB for MongoDB using a service principal.

  1. Install dependencies

    dotnet add package MongoDb.Driver
    dotnet add package Azure.Identity
    
  2. Get an access token for the managed identity or service principal using client library Azure.Identity. Use the access token and AZURE_COSMOS_LISTCONNECTIONSTRINGURL to get the connection string. Get the connection information from the environment variables added by Service Connector and connect to Azure Cosmos DB for MongoDB. When using the code below, uncomment the part of the code snippet for the authentication type you want to use.

    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 MongoDB.Driver;
    using Azure.Identity;
    using System.Text.Json;
    
    var endpoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
    var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
    // Uncomment the following lines according to the authentication type.
    // 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 connection string.
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
    var response = await httpClient.POSTAsync(listConnectionStringUrl);
    var responseBody = await response.Content.ReadAsStringAsync();
    var connectionStrings = JsonSerializer.Deserialize<Dictionary<string, List<Dictionary<string, string>>>>(responseBody);
    string connectionString = connectionStrings["connectionStrings"][0]["connectionString"];
    
    // Connect to Azure Cosmos DB for MongoDB
    var client = new MongoClient(connectionString);
    

Next steps

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