Azure Cosmos DB 中的自助式最低 TLS 版本強制執行

適用於：NoSQL MongoDB Cassandra Gremlin Table

本文討論如何使用自助式 API，為您的 Cosmos DB 帳戶強制執行最低版本的 TLS 通訊協定。

最低 TLS 版本強制執行在 Azure Cosmos DB 中的運作方式

由於 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。

新帳戶與現有帳戶的預設值為 Tls。

重要

從 2023 年 4 月 1 日開始，新帳戶的預設值將會切換為 Tls12。

使用入口網站在 Azure Cosmos DB 中設定最低 TLS 通訊協定

在建立和編輯帳戶時，可在入口網站中使用這項自助式功能。 Azure Cosmos DB 帳戶會強制執行 TLS 1.2 通訊協定。 不過，根據選取的 API 種類，Azure Cosmos DB 也支援下列 TLS 通訊協定。

• MongoDB：TLS 1.2

• Cassandra：TLS 1.2

• 資料表、SQL 和圖形：TLS 1.0、TLS 1.1 和 TLS 1.2

建立帳戶時設定最低 TLS 通訊協定的步驟

如果您使用僅支援 TLS 1.2 的 API 種類，您會在底部的 [網路] 索引標籤中發現 TLS 通訊協定已停用。

如果您使用接受多種 TLS 通訊協定的 API 種類，則可以瀏覽至 [網路] 索引標籤，並且可使用 [最低傳輸層安全性通訊協定] 選項。 只要按下拉式清單並選取所需的通訊協定，即可變更選取的通訊協定。

設定帳戶之後，您可以在 [檢閱 + 建立] 索引標籤的 [網路] 區段底部檢閱，確認選取的 TLS 通訊協定已依照您的指定完成設定。

編輯帳戶時設定最低 TLS 通訊協定的步驟

1. 在 Azure 入口網站上瀏覽至 Azure Cosmos DB 帳戶。

2. 從左側功能表中選取 [網路]，然後選取 [連線能力] 索引標籤。

3. 您會看到 [最低傳輸層安全性通訊協定] 選項。 如果您使用僅支援 TLS 1.2 的 API 種類，則會發現此選項已停用。 否則，您只要按一下所需的 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'
$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 Resource Manager 範本使用此屬性設定搭配參數的基本範例。

{
    {
      "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 中的資料庫安全性概觀。