Skip to content

Cosmos DB Integration (Managed Identity)¶

Use this recipe to connect a .NET Container App to Azure Cosmos DB for NoSQL with managed identity first and a connection string fallback only when you cannot use RBAC yet.

Architecture¶

flowchart TD
    C[Client] --> I[Container Apps Ingress]
    I --> APP[.NET Container App]
    APP --> COSMOS[Azure Cosmos DB]
    APP -.-> MI[Managed Identity]
    MI -.-> ENTRA[Microsoft Entra ID]
    MI -.-> COSMOS

Solid arrows show runtime data flow. Dashed arrows show identity and authentication.

Prerequisites¶

Existing Container App: $APP_NAME in resource group $RG
Existing Azure Cosmos DB account, SQL database, and container
Azure CLI with Container Apps and Cosmos extensions

az extension add --name containerapp --upgrade
az extension add --name cosmosdb-preview --upgrade

Command	Why it is used
`az extension add ...`	Installs or updates the Container Apps Azure CLI extension.

Step 1: Enable managed identity on the Container App¶

az containerapp identity assign \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --system-assigned

export PRINCIPAL_ID=$(az containerapp show \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --query "identity.principalId" \
  --output tsv)

Command	Why it is used
`az containerapp identity assign ...`	Assigns or inspects managed identity configuration for the Container App.

Step 2: Grant Cosmos DB data-plane access¶

export COSMOS_ACCOUNT_ID=$(az cosmosdb show \
  --name "$COSMOS_ACCOUNT" \
  --resource-group "$RG" \
  --query "id" \
  --output tsv)

az role assignment create \
  --assignee-object-id "$PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Cosmos DB Built-in Data Contributor" \
  --scope "$COSMOS_ACCOUNT_ID"

Command	Why it is used
`az cosmosdb show ...`	Creates or inspects Cosmos DB resources used by the sample app.

Step 3: Configure non-secret settings in Container Apps¶

Azure Container Apps does not inject Cosmos DB connection settings automatically. Store non-secret values as environment variables, and store fallback secrets in secrets[] with secretref:.

az containerapp update \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --set-env-vars COSMOS_ENDPOINT="https://$COSMOS_ACCOUNT.documents.azure.com:443/" COSMOS_DATABASE="$COSMOS_DATABASE" COSMOS_CONTAINER="$COSMOS_CONTAINER"

Command	Why it is used
`az containerapp update ...`	Updates the existing Container App configuration without recreating the app.

Step 4: .NET code (managed identity)¶

Add dependencies:

dotnet add package Microsoft.Azure.Cosmos
dotnet add package Azure.Identity

Use DefaultAzureCredential when COSMOS_CONNECTION_STRING is not present:

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

record OrderDocument(string id, string partitionKey, string type, string status);

static CosmosClient CreateClient()
{
    var connectionString = Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING");
    if (!string.IsNullOrWhiteSpace(connectionString))
    {
        return new CosmosClient(connectionString);
    }

    var endpoint = Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!;
    TokenCredential credential = new DefaultAzureCredential();
    return new CosmosClient(endpoint, credential);
}

using var client = CreateClient();
var container = client.GetContainer(
    Environment.GetEnvironmentVariable("COSMOS_DATABASE"),
    Environment.GetEnvironmentVariable("COSMOS_CONTAINER"));

var item = new OrderDocument("order-1001", "order-1001", "order", "created");
await container.UpsertItemAsync(item, new PartitionKey(item.partitionKey));
var response = await container.ReadItemAsync<OrderDocument>(item.id, new PartitionKey(item.partitionKey));

Console.WriteLine(response.Resource);

Step 5: Connection string fallback¶

az containerapp secret set \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --secrets cosmos-connection-string="AccountEndpoint=https://$COSMOS_ACCOUNT.documents.azure.com:443/;AccountKey=<cosmos-account-key>;"

az containerapp update \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --set-env-vars COSMOS_CONNECTION_STRING=secretref:cosmos-connection-string COSMOS_DATABASE="$COSMOS_DATABASE" COSMOS_CONTAINER="$COSMOS_CONTAINER"

Command	Why it is used
`az containerapp secret set ...`	Manages Container Apps secrets without exposing secret values in plain configuration.

Verification¶

Confirm identity assignment.
Confirm the Cosmos DB role assignment exists.
Check app logs for successful upsert and read operations.

See Also¶

Sources¶