Disable key-based authentication with Azure Cosmos DB for NoSQL

This article covers the process of disabling key-based authorization (or resource owner password credential auth) for an Azure Cosmos DB for NoSQL account.

Disabling key-based authorization prevents your account from being used without the more secure Microsoft Entra authentication method. This procedure is a step that should be performed on new accounts in secure workloads. Alternatively, perform this procedure on existing accounts being migrated to a secure workload pattern.

Prerequisites

• An Azure account with an active subscription. Create an account for free.

• Use the Bash environment in Azure Cloud Shell. For more information, see Get started with Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Authenticate to Azure using Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

• If you choose to use Azure PowerShell locally:
  • Install the latest version of the Az PowerShell module.
  • Connect to your Azure account using the Connect-AzAccount cmdlet.
• If you choose to use Azure Cloud Shell:
  • See Overview of Azure Cloud Shell for more information.

Disable key-based authentication

First, disable key-based authentication to your existing account so that applications are required to use Microsoft Entra authentication. Use az resource update to modify properties.disableLocalAuth of the existing account.

az resource update \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-account>" \
    --resource-type "Microsoft.DocumentDB/databaseAccounts" \
    --set properties.disableLocalAuth=true

First, create a new account with key-based authentication disabled so that applications are required to use Microsoft Entra authentication.

1. Create a new Bicep file to deploy your new account with key-based authentication disabled. Name the file deploy-new-account.bicep.

   metadata description = 'Deploys a new Azure Cosmos DB account with key-based auth disabled.'
   
   @description('Name of the Azure Cosmos DB account.')
   param name string = 'csms-${uniqueString(resourceGroup().id)}'
   
   @description('Primary location for the Azure Cosmos DB account.')
   param location string = resourceGroup().location
   
   resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = {
     name: name
     location: location
     kind: 'GlobalDocumentDB'
     properties: {
       databaseAccountOfferType: 'Standard'
       locations: [
         {
           locationName: location
         }
       ]
       disableLocalAuth: true
     }
   }
   

2. Use az deployment group create to deploy the Bicep file with the new account.

   az deployment group create \
       --resource-group "<name-of-existing-resource-group>" \
       --template-file deploy-new-account.bicep
   

First, disable key-based authentication to your existing account so that applications are required to use Microsoft Entra authentication. Use Get-AzResource and Set-AzResource to respectively read and update the existing account.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    ResourceName = "<name-of-existing-account>"
    ResourceType = "Microsoft.DocumentDB/databaseAccounts"
}
$resource = Get-AzResource @parameters

$resource.Properties.DisableLocalAuth = $true


$resource | Set-AzResource -Force

Use these steps to create a new Azure Cosmos DB for NoSQL account with key-based authentication disabled so that applications are required to only use Microsoft Entra authentication.

1. When setting up a new Azure Cosmos DB for NoSQL account, navigate to the Security section of the account creation process.

2. Then, select Disable for the Key-based authentication option.

   

Validate that authentication is disabled

Attempt to use the Azure SDK to connect to Azure Cosmos DB for NoSQL using a resource-owner password credential (ROPC). This attempt should fail. If necessary, code samples for common programming languages are provided here.

C#

using Microsoft.Azure.Cosmos;

string connectionString = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;";

CosmosClient client = new(connectionString);

Important

This code sample uses the Microsoft.Azure.Cosmos library from NuGet.

JavaScript

const { CosmosClient } = require('@azure/cosmos');

const connectionString = 'AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;';

const client = new CosmosClient(connectionString);

Important

This code sample uses the @azure/cosmos package from npm.

TypeScript

import { CosmosClient } from '@azure/cosmos'

let connectionString: string = 'AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;';

const client: CosmosClient = new CosmosClient(connectionString);

Important

This code sample uses the @azure/cosmos package from npm.

Python

from azure.cosmos import CosmosClient

connection_string = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;"

client = CosmosClient(connection_string)

Important

This code sample uses the azure-cosmos package from PyPI.

Go

package main

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

const connectionString = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;"

func main() {
    client, _ := azcosmos.NewClientFromConnectionString(connectionString, nil)
}

Important

This code sample uses the azure/azure-sdk-for-go/sdk/data/azcosmos package from Go.

Java

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;

public class NoSQL{
    public static void main(String[] args){
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<nosql-endpoint>")
            .key("<key>")
            .buildClient();
    }
}

Important

This code samples uses the com.azure/azure-cosmos package from Maven.

Related content

• Security best practices
• Grant data plane role-based access
• Grant data plane control-plane access