Migrate an application to use passwordless connections with Azure Cosmos DB for NoSQL

Article
09/14/2024

Application requests to Azure Cosmos DB for NoSQL must be authenticated. Although there are multiple options for authenticating to Azure Cosmos DB, you should prioritize passwordless connections in your applications when possible. Traditional authentication methods that use connection strings with passwords or secret keys create security risks and complications. Visit the passwordless connections for Azure services hub to learn more about the advantages of moving to passwordless connections.

The following tutorial explains how to migrate an existing application to connect to Azure Cosmos DB for NoSQL using passwordless connections instead of a key-based solution.

Configure roles and users for local development authentication

When developing locally with passwordless authentication, make sure the user account that connects to Cosmos DB is assigned a role with the correct permissions to perform data operations. Currently, Azure Cosmos DB for NoSQL doesn't include built-in roles for data operations, but you can create your own using the Azure CLI or PowerShell.

Roles consist of a collection of permissions or actions that a user is allowed to perform, such as read, write, and delete.

Create the custom role

Create a role using the az role definition create command. Pass in the Cosmos DB account name and resource group, followed by a body of JSON that defines the custom role. The following example creates a role named PasswordlessReadWrite with permissions to read and write items in Cosmos DB containers. The role is also scoped to the account level using /.

az cosmosdb sql role definition create \
    --account-name <cosmosdb-account-name> \
    --resource-group  <resource-group-name> \
    --body '{
    "RoleName": "PasswordlessReadWrite",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ]
    }]
}'

When the command completes, copy the ID value from the name field and paste it somewhere for later use.
Assign the role you created to the user account or service principal that will connect to Cosmos DB. During local development, this will generally be your own account that's logged into a development tool like Visual Studio or the Azure CLI. Retrieve the details of your account using the az ad user command.
```
az ad user show --id "<your-email-address>"
```
Copy the value of the id property out of the results and paste it somewhere for later use.

Assign the custom role you created to your user account using the az cosmosdb sql role assignment create command and the IDs you copied previously.

az cosmosdb sql role assignment create \
    --account-name <cosmosdb-account-name> \
    --resource-group  <resource-group-name> \
    --scope "/" \
    --principal-id <your-user-id> \
    --role-definition-id <your-custom-role-id>

For local development, make sure you're authenticated with the same Microsoft Entra account you assigned the role to. You can authenticate via popular development tools, such as the Azure CLI or Azure PowerShell. The development tools with which you can authenticate vary across languages.

Sign-in to Azure through the Azure CLI using the following command:

az login

You will need to install the Azure CLI to work with DefaultAzureCredential through Visual Studio Code.

On the main menu of Visual Studio Code, navigate to Terminal > New Terminal.

Sign-in to Azure through the Azure CLI using the following command:

az cloud set -n AzureChinaCloud
az login

Sign-in to Azure using PowerShell via the following command:

Connect-AzAccount -Environment AzureChinaCloud

Migrate the app code to use passwordless connections

To use DefaultAzureCredential in a .NET application, install the Azure.Identity package:
```
dotnet add package Azure.Identity
```
At the top of your file, add the following code:
```
using Azure.Identity;
```

Identify the locations in your code that create a CosmosClient object to connect to Azure Cosmos DB. Update your code to match the following example.

DefaultAzureCredential credential = new();

using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT"),
    tokenCredential: credential
);

To use DefaultAzureCredential in a Go application, install the azidentity module:
```
go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity
```

At the top of your file, add the following code:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

Identify the locations in your code that create a Client instance to connect to Azure Cosmos DB. Update your code to match the following example:

cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    // handle error
}

endpoint := os.Getenv("COSMOS_ENDPOINT")
client, err := azblob.NewClient(endpoint, cred, nil)
if err != nil {
    // handle error
}

To use DefaultAzureCredential in a Java application, install the azure-identity package via one of the following approaches:
1. Include the BOM file.
2. Include a direct dependency.

At the top of your file, add the following code:

import com.azure.identity.DefaultAzureCredentialBuilder;

Identify the locations in your code that create a CosmosClient or CosmosAsyncClient object to connect to Azure Cosmos DB. Update your code to match the following example:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();
String endpoint = System.getenv("COSMOS_ENDPOINT");

CosmosClient client = new CosmosClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .consistencyLevel(ConsistencyLevel.EVENTUAL)
    .buildClient();

To use DefaultAzureCredential in a Node.js application, install the @azure/identity package:
```
npm install --save @azure/identity
```

At the top of your file, add the following code:

import { DefaultAzureCredential } from "@azure/identity";

Identify the locations in your code that create a CosmosClient object to connect to Azure Cosmos DB. Update your code to match the following example:

const credential = new DefaultAzureCredential();
const endpoint = process.env.COSMOS_ENDPOINT;

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

To use DefaultAzureCredential in a Python application, install the azure-identity package:
```
pip install azure-identity
```

At the top of your file, add the following code:

from azure.identity import DefaultAzureCredential

Identify the locations in your code that create a BlobServiceClient object to connect to Azure Blob Storage. Update your code to match the following example:
```
credential = DefaultAzureCredential()
endpoint = os.environ["COSMOS_ENDPOINT"]

client = CosmosClient(
    url = endpoint,
    credential = credential
)
```

Run the app locally

After making these code changes, run your application locally. The new configuration should pick up your local credentials, such as the Azure CLI, Visual Studio, or IntelliJ. The roles you assigned to your local dev user in Azure allows your app to connect to the Azure service locally.

Configure the Azure hosting environment

Once your application is configured to use passwordless connections and runs locally, the same code can authenticate to Azure services after it's deployed to Azure. The sections that follow explain how to configure a deployed application to connect to Azure Cosmos DB using a managed identity.

Create the managed identity

You can create a user-assigned managed identity using the Azure portal or the Azure CLI. Your application uses the identity to authenticate to other services.

Azure portal
Azure CLI

At the top of the Azure portal, search for Managed identities. Select the Managed Identities result.
Select + Create at the top of the Managed Identities overview page.
On the Basics tab, enter the following values:
- Subscription: Select your desired subscription.
- Resource Group: Select your desired resource group.
- Region: Select a region near your location.
- Name: Enter a recognizable name for your identity, such as MigrationIdentity.
Select Review + create at the bottom of the page.
When the validation checks finish, select Create. Azure creates a new user-assigned identity.

After the resource is created, select Go to resource to view the details of the managed identity.

Use the az identity create command to create a user-assigned managed identity:

az identity create --name MigrationIdentity --resource-group <your-resource-group>

Associate the managed identity with your web app

You need to configure your web app to use the managed identity you created. Assign the identity to your app using either the Azure portal or the Azure CLI.

Azure portal
Azure CLI

Complete the following steps in the Azure portal to associate an identity with your app. These same steps apply to the following Azure services:

Azure Spring Apps
Azure Container Apps
Azure virtual machines
Azure Kubernetes Service

Navigate to the overview page of your web app.
Select Identity from the left navigation.
On the Identity page, switch to the User assigned tab.
Select + Add to open the Add user assigned managed identity flyout.
Select the subscription you used previously to create the identity.
Search for the MigrationIdentity by name and select it from the search results.
Select Add to associate the identity with your app.

Use the following Azure CLI commands to associate an identity with your app:

Retrieve the ID of the managed identity you created using the az identity show command. Copy the output value to use in the next step.

az identity show --name MigrationIdentity -g <your-identity-resource-group-name> --query id

You can assign a managed identity to an Azure App Service instance with the az webapp identity assign command.

az webapp identity assign \
    --resource-group <resource-group-name> \
    --name <webapp-name>
    --identities <managed-identity-id>

You can assign a managed identity to an Azure Spring Apps instance with the az spring app identity assign command.

az spring app identity assign \
    --resource-group <resource-group-name> \
    --name <app-name> \
    --service <service-name>
    --user-assigned <managed-identity-id>

You can assign a managed identity to a virtual machine with the az vm identity assign command.

az vm identity assign \
    --resource-group <resource-group-name> \
    --name <virtual-machine-name>
    --identities <managed-identity-id>

You can assign a managed identity to an Azure Kubernetes Service (AKS) instance with the az aks update command.

az aks update \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --enable-managed-identity \
    --assign-identity <managed-identity-id> \
    --assign-kubelet-identity <managed-identity-id>

Assign roles to the managed identity

Grant permissions to the managed identity by assigning it the custom role you created, just like you did with your local development user.

Assign roles using the az role assignment command of the Azure CLI.

az cosmosdb sql role assignment create \
    --account-name <cosmosdb-account-name> \
    --resource-group  <resource-group-name> \
    --scope "/" \
    --principal-id <managed-identity-id> \
    --role-definition-id <your-custom-role-id>

Update the application code

You need to configure your application code to look for the specific managed identity you created when it's deployed to Azure. In some scenarios, explicitly setting the managed identity for the app also prevents other environment identities from accidentally being detected and used automatically.

On the managed identity overview page, copy the client ID value to your clipboard.
Apply the following language-specific changes:
- .NET
- Go
- Java
- Node.js
- Python
Create a DefaultAzureCredentialOptions object and pass it to DefaultAzureCredential. Set the ManagedIdentityClientId property to the client ID.
```
DefaultAzureCredential credential = new(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = managedIdentityClientId
    });
```
Set the AZURE_CLIENT_ID environment variable to the managed identity client ID. DefaultAzureCredential reads this environment variable.
Call the managedIdentityClientId method. Pass the client ID to it.
```
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .managedIdentityClientId(managedIdentityClientId)
    .build();
```
Create a DefaultAzureCredentialClientIdOptions object with its managedIdentityClientId property set to the client ID. Pass that object to the DefaultAzureCredential constructor.
```
const credential = new DefaultAzureCredential({
  managedIdentityClientId
});
```
Set the DefaultAzureCredential constructor's managed_identity_client_id parameter to the client ID.
```
credential = DefaultAzureCredential(
    managed_identity_client_id = managed_identity_client_id
)
```
Redeploy your code to Azure after making this change in order for the configuration updates to be applied.

Test the app

After deploying the updated code, browse to your hosted application in the browser. Your app should be able to connect to Cosmos DB successfully. Keep in mind that it may take several minutes for the role assignments to propagate through your Azure environment. Your application is now configured to run both locally and in a production environment without the developers having to manage secrets in the application itself.

Next steps

In this tutorial, you learned how to migrate an application to passwordless connections.

You can read the following resources to explore the concepts discussed in this article in more depth:

Authorize access to blobs using Microsoft Entra ID)
To learn more about .NET, see Get started with .NET in 10 minutes.

Migrate an application to use passwordless connections with Azure Cosmos DB for NoSQL

Configure roles and users for local development authentication

Create the custom role

Sign-in to Azure locally

Migrate the app code to use passwordless connections

Run the app locally

Configure the Azure hosting environment

Create the managed identity

Associate the managed identity with your web app

Assign roles to the managed identity

Update the application code

Test the app

Next steps

Additional resources