在 Azure Cosmos DB 中自助强制实施最低 TLS 版本
适用对象: 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
。
重要
从 2024 年 10 月 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 协议。
如果使用的 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
后续步骤
有关 Azure Cosmos DB 中的安全性的详细信息,请参阅 Azure Cosmos DB 中的数据库安全性概述。