你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

项目
09/03/2024

适用对象： NoSQL MongoDB Cassandra Gremlin 表

本文介绍如何使用自助服务 API 为 Cosmos DB 帐户强制实施最低版本的 TLS 协议。

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

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

接受的最低服务范围的版本为 TLS 1.0。此选择可以基于帐户进行更改，如下一部分所述。

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

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

Tls 用于将最低版本设置为 TLS 1.0。
Tls11 用于将最低版本设置为 TLS 1.1。
Tls12 用于将最低版本设置为 TLS 1.2。

新帐户的默认值为 Tls12。

重要

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

通过门户设置 Azure Cosmos DB 中的最低 TLS 协议

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

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

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

如果使用的 API 类型仅支持 TLS 1.2，你会注意到底部的“网络”选项卡中禁用了 TLS 协议。

仅支持 TLS 1.2 的 API 类型的屏幕截图。

如果使用的 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'
$patchParameters = @{
  ResourceGroupName = 'myresourcegroup'
  Name = 'mycosmosdbaccount'
  ResourceProviderName = 'Microsoft.DocumentDB'
  ResourceType = 'databaseaccounts'
  ApiVersion = '2022-11-15'
  Payload = "{ 'properties': {
      'minimalTlsVersion': '$minimalTlsVersion'
  } }"
  Method = 'PATCH'
}
Invoke-AzRestMethod @patchParameters

通过 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 中将 PATCH 方法更改为 PUT，来创建设置了 minimalTlsVersion 属性的帐户。请确保包含帐户的其他属性。

重要

如果该帐户存在并且 PUT 请求中省略了 minimalTlsVersion 属性，则从 2022-11-15 API 版本开始，该属性将重置为默认值。

如何验证是否强制实施了最低 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 获取该属性的当前值，请运行以下命令：

$getParameters = @{
  ResourceGroupName = 'myresourcegroup'
  Name = 'mycosmosdbaccount'
  ResourceProviderName = 'Microsoft.DocumentDB'
  ResourceType = 'databaseaccounts'
  ApiVersion = '2022-11-15'
  Method = 'GET'
}
Invoke-AzRestMethod @getParameters

通过