Azure Cosmos DB Shell 安全最佳做法

使用这些全面的安全最佳做法保护 Azure Cosmos DB Shell 部署。

身份验证方法

1. Microsoft Entra ID （建议）

最适合： 开发、测试和生产环境

优点：

最安全的身份验证方法
本地未存储任何凭据
自动令牌刷新
支持多重身份验证（MFA）
Azure中的完整审核线索

实现：

在没有连接参数的情况下启动时，Cosmos DB Shell 将启动断开连接。使用 Microsoft Entra ID 连接到帐户终结点进行身份验证：

cosmosdbshell
CS > connect https://<account-name>.documents.azure.cn:443/ --auth-method entra-id

运行 connect 后，浏览器将打开Azure登录。完成该流程后，Shell 将使用你的 Microsoft Entra ID 凭据。

配置：

connect <account_endpoint> --auth-method entra-id

安全优势：

凭据从不存储在磁盘上
令牌自动刷新
MFA 提供额外的保护
RBAC 控制可以访问的内容

2. 托管标识（生产）

最适合： 托管在 Azure 上的应用程序和生产环境

优点：

不需要凭据管理
自动令牌刷新
适用于Azure服务（应用服务、函数、AKS）
没有要轮换的密码
增强Azure安全性

实现：

在Azure资源上启用托管标识：

对于应用服务：

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

在 Cosmos DB Shell 中：

cosmosdbshell --auth-method managed-identity

安全配置：

在Azure资源上启用托管标识
将 Cosmos DB RBAC 角色分配给标识
Shell 自动使用标识凭据
不需要机密

优点：

零凭据管理
自动令牌轮换
所有操作的审计跟踪
符合安全标准

3. 帐户密钥（仅限开发）

最适合： 仅限本地开发和测试

缺点：

本地存储的密钥（安全风险）
需要手动轮换
单一故障点
无法使用多重身份验证
不建议用于生产

实现：

cosmosdbshell --connection-string "<connection_string>"

最低风险使用：

仅开发/测试
切勿提交到源代码管理系统
使用环境变量：

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

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

凭据管理

最佳做法

1. 从不硬编码凭据

❌ 错误：

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

✅ 良好：

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

2. 使用环境变量

发展：

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

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

3.在安全保管库中存储

Azure 密钥保管库：

# 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"

本地开发：

使用 .env 文件（添加到 .gitignore）
通过环境变量加载
切勿提交敏感凭据

4.定期轮换密钥

密钥轮换过程：

在 Azure 门户中生成新密钥
使用新密钥更新应用程序
验证后删除旧密钥
测试所有应用程序是否正常运行

RBAC （基于角色的访问控制）

实现最低特权

原则： 授予所需的最低权限

建议的角色：

角色	用例	Permissions
`Cosmos DB Account Reader`	只读访问	查看数据、元数据
`Cosmos DB Built-in Data Reader`	查询操作	执行查询，读取文档
`Cosmos DB Built-in Data Contributor`	完全数据访问	创建、读取、更新、删除文档

分配角色：

# 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"

按容器限定访问范围

创建具有有限容器访问权限的自定义角色：

# 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

数据保护

1. 传输中的加密

TLS 1.2+ （默认）

Cosmos DB Shell 使用 TLS 1.2 或更高版本：

# Verify TLS version
cosmosdbshell --tls-version 1.2

配置：

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

2. 静态加密

启用静态加密：

Azure 会自动进行加密，但请确认：

转到 Azure 门户 > Cosmos DB 帐户
设置 > 静态加密
验证是否已启用加密

验证：

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

3. 客户管理的密钥（CMK）

为了增强安全性：

创建 Azure 密钥保管库
生成加密密钥
将 Cosmos DB 配置为使用 CMK

设置：

# 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)

网络安全

1. IP 防火墙

启用防火墙：

Azure门户 > Cosmos DB 帐户 > 防火墙
添加您的 IP 地址
保存更改

命令行：

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

2. 虚拟终结点

限制到 VNet：

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

3. 专用终结点

实现最大程度的网络隔离：

在 Azure 门户中创建专用终结点
配置 DNS 设置
Shell 通过专用网络进行连接

优点：

无互联网暴露
受限网络访问
支持企业网络隔离策略

MCP 服务器安全性

1.仅本地绑定（默认值）

配置：

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

为什么重要：

阻止远程访问
只有本地进程才能连接
减少攻击面
推荐： 保持启用状态

2. MCP 身份验证

Microsoft Entra ID 身份验证：

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

3. MCP 端口安全性

安全配置：

{
  "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. MCP 的防火墙规则

阻止外部访问：

# 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

审核和监视

1.启用审核日志记录

Azure审核日志：

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

2. 监控 MCP 活动

启用 MCP 日志记录：

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

查看日志：

VS Code 输出面板
Application Insights
Azure Monitor

3. 查询指标

监控查询性能：

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

要跟踪的指标：

使用的请求单位（RU）
执行时间
项目数

合规性和标准

1. 数据驻留

确保数据保留在区域中：

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

2. 合规性标准

Azure Cosmos DB维护一套广泛的合规性认证。

有关最新的认证和审核报告，请参阅Azure合规性产品/服务。
有关此服务的特定合规性信息，请参阅 Azure Cosmos DB 中的合规性。

3. 数据保留期

为敏感数据设置生存时间（TTL）：

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

这会在 30 天后删除文档。

安全清单

[ ] 使用Microsoft Entra ID进行身份验证
[ ] 在 Azure 帐户上启用 MFA
[ ] 实施最小权限 RBAC
[ ] 启用 IP 防火墙
[ ] 使用加密连接（TLS 1.2+）
[ ] 启用审核日志记录
[ ] 监视 MCP 服务器活动
[ ] 在密钥保管库中存储凭据
[ ] 定期轮换密钥
[ ] 在生产中使用专用终结点
[ ] 启用静态加密
[ ] 查看符合性要求
[ ] 记录安全策略
[ ] 根据安全做法培训用户

常见安全错误

❌ 将密钥存储在代码中

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

✅ 使用环境变量

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

❌ 在生产环境中使用帐户密钥

# DON'T use keys in production
cosmosdbshell --auth-method key

✅ 使用托管标识

# DO use managed identity
cosmosdbshell --auth-method managed-identity

❌ 让 MCP 保持打开状态

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

✅ 限制 MCP 访问

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

安全资源

后续步骤

安装指南 - 安全入门
命令参考 - 了解可用的命令
快速入门指南 - 安全示例
MCP 安装指南 - 安全 MCP 配置

支持

有关安全问题或漏洞报告：

另请参阅

Last updated on 2026-06-05

Azure Cosmos DB Shell 安全最佳做法

身份验证方法

1. Microsoft Entra ID （建议）

2. 托管标识 （生产）

3. 帐户密钥（仅限开发）

凭据管理

最佳做法

1. 从不硬编码凭据

2. 使用环境变量

3.在安全保管库中存储

4.定期轮换密钥

RBAC （基于角色的访问控制）

实现最低特权

按容器限定访问范围

数据保护

1. 传输中的加密

2. 静态加密

3. 客户管理的密钥 （CMK）

网络安全

1. IP 防火墙

2. 虚拟终结点

3. 专用终结点

MCP 服务器安全性

1.仅本地绑定（默认值）

2. MCP 身份验证

3. MCP 端口安全性

4. MCP 的防火墙规则

审核和监视

1.启用审核日志记录

2. 监控 MCP 活动

3. 查询指标

合规性和标准

1. 数据驻留

2. 合规性标准

3. 数据保留期

安全清单

常见安全错误

❌ 将密钥存储在代码中

✅ 使用环境变量

❌ 在生产环境中使用帐户密钥

✅ 使用托管标识

❌ 让 MCP 保持打开状态

✅ 限制 MCP 访问

安全资源

后续步骤

支持

另请参阅

其他资源

2. 托管标识（生产）

3. 客户管理的密钥（CMK）