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

适用对象： 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 API 版本开始，将为每个 Cosmos DB 数据库帐户公开一个名为 的新属性minimalTlsVersion。 它接受以下值：

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

新帐户的默认值为 Tls12。

通过门户设置 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.2

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

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

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

设置帐户后，可以在底部“网络”部分的“查看 + 创建”选项卡中查看是否已按指定设置所选 TLS 协议。

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

1. 在 Azure 门户中，导航到你的 Azure Cosmos DB 帐户。

2. 从左侧菜单中选择“网络”，然后选择“连接”选项卡。

3. 你将找到“最低传输层安全协议”选项。 如果使用的 API 种类仅支持 TLS 1.2，你会发现此选项已禁用。 如果并非如此，只需单击选择所需的 TLS 协议即可。

4. 更改 TLS 协议后，单击“保存”。

5. 保存后，你将收到成功通知。 不过，在配置更新完成后，此更改最多可能需要 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

相关内容

• 为即将到来的 Azure Cosmos DB 的 TLS 1.3 支持做好准备
• 迁移到适用于 Azure Cosmos DB 的 TLS 1.2