Azure Cosmos DB Shell security best practices

Applies to: ✅ NoSQL

Secure your Azure Cosmos DB Shell deployments with these comprehensive security best practices.

Authentication methods

1. Microsoft Entra ID (recommended)

Best for: Development, testing, and production environments

Advantages:

Most secure authentication method
No credentials stored locally
Automatic token refresh
Supports multifactor authentication (MFA)
Full audit trail in Azure

Implementation:

When launched without connection arguments, Cosmos DB Shell starts disconnected. Authenticate by connecting to your account endpoint with Microsoft Entra ID:

cosmosdbshell
CS > connect https://<account-name>.documents.azure.com:443/ --tenant=<tenant-id>

The browser opens for Azure sign-in after you run connect. Complete the flow and the shell uses your Microsoft Entra ID credentials.

Configuration:

connect <account_endpoint> --tenant=<tenant-id>

Security Benefits:

Credentials never stored on disk
Tokens automatically refreshed
MFA provides additional protection
RBAC controls what you can access

2. Managed identity (production)

Best for: Azure-hosted applications and production environments

Advantages:

No credential management required
Automatic token refresh
Works with Azure services (App Service, Functions, AKS)
No secrets to rotate
Enhanced security in Azure

Implementation:

Enable managed identity on Azure resource:

For App Service:

{
  "identity": {
    "type": "SystemAssigned"
  }
}

From your terminal:

cosmosdbshell --connect https://<account-name>.documents.azure.com:443/ --connect-managed-identity=<client-id>

Security Configuration:

Enable managed identity on Azure resource
Assign Cosmos DB RBAC role to identity
Shell automatically uses identity credentials
No secrets needed

Benefits:

Zero credential management
Automatic token rotation
Audit trail for all operations
Complies with security standards

3. Account key (development only)

Best for: Local development and testing only

Disadvantages:

Keys stored locally (security risk)
Manual rotation required
Single point of failure
Cannot use MFA
Not recommended for production

Implementation:

cosmosdbshell --connection-string "<connection_string>"

Minimal Risk Usage:

Development/testing only
Never commit to source control
Use environment variables:

# Set environment variable
export COSMOS_CONNECTION_STRING="your-connection-string"

# Use in script
cosmosdbshell --connection-string "$COSMOS_CONNECTION_STRING"

Credential management

Best practices

1. Never hardcode credentials

❌ Bad:

#!/bin/bash
cosmosdbshell --connection-string "DefaultEndpointProtocol=https;AccountName=myaccount;..."

✅ Good:

#!/bin/bash
cosmosdbshell --connection-string "$COSMOS_CONNECTION_STRING"

2. Use environment variables

Development:

# .env file (development only)
COSMOS_CONNECTION_STRING="your-connection-string"

# Load and use
source .env
cosmosdbshell --connection-string "$COSMOS_CONNECTION_STRING"

3. Store in secure vaults

Azure Key Vault:

# Store connection string
az keyvault secret set --vault-name myKeyVault \
  --name cosmos-connection-string \
  --value "your-connection-string"

# Retrieve and use
CONNECTION_STRING=$(az keyvault secret show \
  --vault-name myKeyVault \
  --name cosmos-connection-string \
  --query value -o tsv)

cosmosdbshell --connection-string "$CONNECTION_STRING"

Local Development:

Use .env files (add to .gitignore)
Load via environment variables
Never commit secrets

4. Rotate keys regularly

Key Rotation Process:

Generate new key in Azure portal
Update applications with new key
Delete old key after verification
Test all applications work

RBAC (role-based access control)

Implement least privilege

Principle: Grant minimum permissions needed

Recommended Roles:

Role	Use Case	Permissions
`Cosmos DB Account Reader`	Read-only access	View data, metadata
`Cosmos DB Built-in Data Reader`	Query operations	Execute queries, read documents
`Cosmos DB Built-in Data Contributor`	Full data access	Create, read, update, delete documents

Assign Roles:

# Get resource ID
RESOURCE_ID=$(az cosmosdb show \
  --resource-group myResourceGroup \
  --name myaccount \
  --query id -o tsv)

# Assign role to user
az role assignment create \
  --role "Cosmos DB Built-in Data Reader" \
  --assignee "<user-principal-id>" \
  --scope "$RESOURCE_ID"

Scope access by container

Create custom roles with limited container access:

# Custom role for specific container
cat > custom-role.json << 'EOF'
{
  "Name": "Cosmos DB Container Reader",
  "Description": "Read-only access to specific container",
  "Actions": [
    "Microsoft.DocumentDB/databaseAccounts/readonlyKeys/action",
    "Microsoft.DocumentDB/databaseAccounts/read/action"
  ],
  "DataActions": [
    "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read"
  ],
  "NotDataActions": []
}
EOF

Data protection

1. Encryption in transit

TLS 1.2+ (Default)

Cosmos DB Shell uses TLS 1.2 or later:

# Verify TLS version
cosmosdbshell --tls-version 1.2

Configuration:

# Force TLS 1.3
cosmosdbshell --min-tls-version 1.3

2. Encryption at rest

Enable Encryption at Rest:

Azure handles encryption automatically, but verify:

Go to Azure portal > Cosmos DB Account
Settings > Encryption at Rest
Verify encryption is enabled

Verify:

# Check encryption settings
az cosmosdb show --resource-group myResourceGroup \
  --name myaccount \
  --query "encryption.keyWrapperProperties" -o table

3. Customer-managed keys (CMK)

For Enhanced Security:

Create Azure Key Vault
Generate encryption key
Configure Cosmos DB to use CMK

Setup:

# Create key vault
az keyvault create --resource-group myResourceGroup \
  --name myKeyVault

# Create key
az keyvault key create --vault-name myKeyVault \
  --name cosmos-key

# Configure Cosmos DB (via Portal or Terraform)

Network security

1. IP firewall

Enable Firewall:

Azure portal > Cosmos DB Account > Firewall
Add your IP address(es)
Save changes

Command Line:

# Add IP to firewall
az cosmosdb update --resource-group myResourceGroup \
  --name myaccount \
  --ip-range-filter "203.0.113.0/24"

2. Virtual endpoints

Restrict to VNet:

# Enable virtual endpoint
az cosmosdb update --resource-group myResourceGroup \
  --name myaccount \
  --enable-virtual-network true

3. Private endpoints

For Maximum Network Isolation:

Create private endpoint in Azure portal
Configure DNS settings
Shell connects via private network

Benefits:

No internet exposure
Restricted network access
Supports enterprise network isolation policies

MCP server security

1. Local-only binding (default)

Configuration:

{
  "cosmosDB.shell.MCP.bindToLocalhost": true
}

Why Important:

Prevents remote access
Only local processes can connect
Reduces attack surface
Recommended: Keep enabled

2. Authentication for MCP

Microsoft Entra ID authentication:

{
  "cosmosDB.shell.MCP.enabled": true,
  "cosmosDB.shell.MCP.authMethod": "entra-id"
}

3. MCP port security

Secure Configuration:

{
  "cosmosDB.shell.MCP.enabled": true,
  "cosmosDB.shell.MCP.port": 6128,
  "cosmosDB.shell.MCP.bindToLocalhost": true,
  "cosmosDB.shell.MCP.tlsEnabled": true,
  "cosmosDB.shell.MCP.tlsCertPath": "/path/to/cert.pem"
}

4. Firewall rules for MCP

Block External Access:

# Windows Firewall
netsh advfirewall firewall add rule name="Block MCP" \
  dir=in action=block protocol=tcp localport=6128

# Linux/macOS (iptables)
sudo iptables -A INPUT ! -i lo -p tcp --dport 6128 -j DROP

Audit and monitoring

1. Enable audit logging

Azure Audit Logs:

# View audit logs
az monitor activity-log list \
  --resource-group myResourceGroup \
  --query "[?resourceId=='<cosmos-resource-id>']"

2. Monitor MCP activity

Enable MCP Logging:

{
  "cosmosDB.shell.MCP.logLevel": "info"
}

Review Logs:

VS Code Output panel
Application Insights
Azure Monitor

3. Query metrics

Monitor Query Performance:

# Review query metrics
CS > query "SELECT * FROM c" --show-metrics

Metrics to Track:

Request units (RU) used
Execution time
Item count

Compliance and standards

1. Data residency

Ensure Data Stays in Region:

# Deploy Cosmos DB in specific region
az cosmosdb create --resource-group myResourceGroup \
  --name myaccount \
  --locations regionName="East US" \
  --databases only

2. Compliance standards

Azure Cosmos DB maintains a broad set of compliance certifications.

For the latest certifications and audit reports, see Microsoft Azure Compliance offerings.
For compliance information specific to this service, see compliance in Azure Cosmos DB.

3. Data retention

Set Time-to-Live (TTL) for Sensitive Data:

CS > mkcon sensitive_data -pk /id --ttl 2592000

This deletes documents after 30 days.

Security checklist

[ ] Use Microsoft Entra ID for authentication
[ ] Enable MFA on Azure account
[ ] Implement least-privilege RBAC
[ ] Enable IP firewall
[ ] Use encrypted connections (TLS 1.2+)
[ ] Enable audit logging
[ ] Monitor MCP server activity
[ ] Store credentials in Key Vault
[ ] Rotate keys regularly
[ ] Use private endpoints in production
[ ] Enable encryption at rest
[ ] Review compliance requirements
[ ] Document security policies
[ ] Train users on security practices

Common security mistakes

❌ Storing keys in code

# DON'T do this
cosmosdbshell --connection-string "DefaultEndpointProtocol=https;AccountKey=abc123"

✅ Use environment variables

# DO this
export COSMOS_CONNECTION_STRING="..."
cosmosdbshell --connection-string "$COSMOS_CONNECTION_STRING"

❌ Using account key in production

# DON'T use keys in production with hardcoded connection strings
cosmosdbshell --connect "AccountEndpoint=https://myaccount.documents.azure.com:443/;AccountKey=<your-account-key>;"

✅ Use managed identity

# DO use managed identity
cosmosdbshell --connect https://<account-name>.documents.azure.com:443/ --connect-managed-identity=<client-id>

❌ Leaving MCP open

// DON'T expose MCP publicly
{
  "cosmosDB.shell.MCP.bindToLocalhost": false
}

✅ Restrict MCP access

// DO restrict to localhost
{
  "cosmosDB.shell.MCP.bindToLocalhost": true
}

Security resources

AI tools

Use these actions to discuss documented security guidance without sharing secrets.

For documentation-only retrieval, use the Microsoft Learn MCP server. For a compact guide index, use the Shell documentation index (llms.txt). The index doesn't change crawler permissions or guarantee retrieval.

Shell MCP requires separate setup and can read or change data under the configured permissions, so review tool calls before approving them. Don't share credentials or sensitive data.

Connect your AI agent
Review authentication and permissions before enabling Shell MCP.

Read as Markdown
Open a text version to copy into your assistant.

Ask ChatGPT
Explain authentication, access controls, and MCP precautions.

Ask Claude
Explain authentication, access controls, and MCP precautions.

ChatGPT and Claude receive only the public article URL and a starter prompt. You might need to sign in. If retrieval fails, copy the Markdown text. These links don't configure database access. An assistant's explanation isn't a security assessment of your deployment.

Support

For security concerns or vulnerability reports:

Feedback

Was this page helpful?

Last updated on 2026-10-29

Azure Cosmos DB Shell security best practices

Authentication methods

1. Microsoft Entra ID (recommended)

2. Managed identity (production)

3. Account key (development only)

Credential management

Best practices

1. Never hardcode credentials

2. Use environment variables

3. Store in secure vaults

4. Rotate keys regularly

RBAC (role-based access control)

Implement least privilege

Scope access by container

Data protection

1. Encryption in transit

2. Encryption at rest

3. Customer-managed keys (CMK)

Network security

1. IP firewall

2. Virtual endpoints

3. Private endpoints

MCP server security

1. Local-only binding (default)

2. Authentication for MCP

3. MCP port security

4. Firewall rules for MCP

Audit and monitoring

1. Enable audit logging

2. Monitor MCP activity

3. Query metrics

Compliance and standards

1. Data residency

2. Compliance standards

3. Data retention

Security checklist

Common security mistakes

❌ Storing keys in code

✅ Use environment variables

❌ Using account key in production

✅ Use managed identity

❌ Leaving MCP open

✅ Restrict MCP access

Security resources

AI tools

Support

Related content

Feedback

Additional resources