在 Azure Cosmos DB 中自助强制实施最低 TLS 版本

2025-08-15

适用对象： NoSQL MongoDB Cassandra Gremlin 表

本文介绍如何使用自助服务 API 为 Cosmos DB 帐户强制实施最低版本的传输层安全性（TLS）协议。

在 Azure Cosmos DB 中强制实施最低 TLS 版本的方式

Cosmos DB 的多租户性质要求该服务满足每个用户的访问和安全需求。为此，Cosmos DB 在 应用程序层强制实施最低 TLS 协议，而不是在运行 TLS 的网络堆栈的较低层实施。将根据客户在特定数据库帐户中指定的设置，对发往该帐户的任何经过身份验证的请求强制实施这种做法。

接受的最低服务版本是 TLS 1.2。可以按帐户更改此选择，如以下部分所述。

如何为 Cosmos DB 数据库帐户设置最低 TLS 版本

从 Azure Cosmos DB 资源提供程序 API 版本 2022-11-15 开始，将为每个名为 minimalTlsVersionCosmos DB 数据库帐户的新属性公开。它接受以下值：

Tls12 用于将最低版本设置为 TLS 1.2

新帐户的默认值为 Tls12。

重要

从 2025 年 8 月 31 日起，所有 Cosmos DB 数据库帐户都必须使用传输层安全性（TLS） 1.2 或更高版本，因为对 TLS 1.0 和 1.1 的支持已停用。

自 2025 年 3 月 31 日起， 为 Azure Cosmos DB 启用对 TLS 1.3 的支持。

使用 Azure 门户设置最低 TLS 协议

创建和编辑帐户时，可在 Azure 门户中使用此自助服务功能。 Azure Cosmos DB 帐户强制实施 TLS 1.2 协议。但是，Azure Cosmos DB 还支持以下 TLS 协议（具体取决于所选的 API 类型）。

MongoDB：TLS 1.2
Cassandra：TLS 1.2
表、SQL 和图形： TLS 1.2

创建帐户时设置最低 TLS 协议的步骤

如果使用仅支持 TLS 1.2 的 API 种类，则会在 “网络 ”选项卡中注意到 TLS 协议已禁用。

如果使用接受多个 TLS 协议的 API 种类，则可以导航到 “网络 ”选项卡，并且“ 最低传输层安全协议 ”选项可用。只需单击下拉列表并选择所需的协议即可更改所选协议。

设置帐户后，可以在“ 查看 + 创建 ”选项卡的“ 网络”下查看所选 TLS 协议已设置为指定。

已按您的指定设置了所选 TLS 协议，屏幕截图如下。

编辑帐户时设置最低 TLS 协议的步骤

在 Azure 门户中，导航到你的 Azure Cosmos DB 帐户。
从边栏菜单中选择 “网络 ”，然后选择“ 连接 ”选项卡。
你将找到 “最低传输层安全协议 ”选项。如果使用的 API 种类仅支持 TLS 1.2，你会发现此选项已禁用。否则，只需单击该协议即可选择所需的 TLS 协议。
更改 TLS 协议后，选择“ 保存 ”。
保存后，你将收到成功通知。不过，在配置更新完成后，此更改最多可能需要 15 分钟才能生效。

通过 Azure CLI 进行设置

若要使用 Azure CLI 进行设置，请使用以下命令：

rg="myresourcegroup"
dbName="mycosmosdbaccount"
minimalTlsVersion="Tls12"
az cosmosdb update -n $dbName -g $rg --minimal-tls-version $minimalTlsVersion

通过 Azure PowerShell 进行设置

若要使用 Azure PowerShell 进行设置，请使用以下命令：

$minimalTlsVersion = "Tls12"
Update-AzCosmosDBAccount -ResourceGroupName myresourcegroup -Name mycosmosdbaccount -MinimalTlsVersion $minimalTlsVersion

通过 ARM 模板进行设置

若要使用 ARM 模板设置此属性，请更新现有模板或为当前部署导出新模板，然后将 "minimalTlsVersion" 添加到 databaseAccounts 资源的属性并指定所需的最低 TLS 版本值。以下示例演示了一个基本 Azure 资源管理器模板，该模板使用参数设置此属性。

{
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "name": "mycosmosdbaccount",
      "apiVersion": "2022-11-15",
      "location": "[parameters('location')]",
      "kind": "GlobalDocumentDB",
      "properties": {
        "consistencyPolicy": {
          "defaultConsistencyLevel": "[parameters('defaultConsistencyLevel')]",
          "maxStalenessPrefix": 1,
          "maxIntervalInSeconds": 5
        },
        "locations": [
          {
            "locationName": "[parameters('location')]",
            "failoverPriority": 0
          }
        ],
        "locations": "[variable('locations')]",
        "databaseAccountOfferType": "Standard",
        "minimalTlsVersion": "[parameters('minimalTlsVersion')]",
      }
    }
}

重要

在使用此属性重新部署时，请确保包含用于帐户和子资源的其他属性。请勿按原样部署此模板，否则将重置所有帐户属性。

对于新帐户

可以使用前面的 ARM 模板或使用 Azure CLI 或 Azure PowerShell 创建具有 minimalTlsVersion 属性集的帐户：

az cosmosdb create --name <CosmosDBAccountName> \
  --resource-group <ResourceGroupName> \
  --kind GlobalDocumentDB \
  --locations regionName=<Region> \
  --minimal-tls-version "Tls12"

New-AzCosmosDBAccount `
  -ResourceGroupName "<YourResourceGroupName>" `
  -Name "<YourCosmosDBAccountName>" `
  -Location "<AzureRegion>" `
  -Kind GlobalDocumentDB `
  -EnableAutomaticFailover $true `
  -MinimalTlsVersion "Tls12"

如何验证是否强制实施了最低 TLS 版本

由于 Cosmos DB 在应用程序层强制实施最低 TLS 版本，因此用于检查特定 TLS 版本的服务是否接受握手的传统 TLS 扫描程序不够可靠，不可用于测试 Cosmos DB 中是否强制实施了这种做法。为了验证实施情况，请参阅官方的开源 cosmos-tls-scanner 工具。

还可以使用 Azure CLI 或 Azure PowerShell 获取 minimalTlsVersion 属性的当前值。

通过 Azure CLI 获取当前值

若要使用 Azure CLI 获取该属性的当前值，请运行以下命令：

subId=$(az account show --query id -o tsv)
rg="myresourcegroup"
dbName="mycosmosdbaccount"
az rest --uri "/subscriptions/$subId/resourceGroups/$rg/providers/Microsoft.DocumentDB/databaseAccounts/$dbName?api-version=2022-11-15" --method GET

通过 Azure PowerShell 获取当前值

若要使用 Azure PowerShell 获取该属性的当前值，请运行以下命令：

Get-AzCosmosDBAccount -ResourceGroupName myresourcegroup -Name mycosmosdbaccount

通过