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

發行項
10/04/2024

適用於：NoSQL MongoDB Cassandra Gremlin 資料表

本文討論如何使用自助式 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。

新帳戶的預設值為 Tls12。

重要

從 2025 年 8 月 31 日起，所有 Cosmos DB 資料庫帳戶都必須使用傳輸層安全性（TLS） 1.2 或更高版本，因為 TLS 1.0 和 1.1 的支援將會停止。

使用入口網站在 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 1.2的 API 種類螢幕擷取畫面。

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

接受多個 TLS 通訊協定的 API 種類螢幕擷取畫面。

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

選取 TLS 通訊協定的螢幕擷取畫面已設定為您指定的內容。

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

在 Azure 入口網站上瀏覽至 Azure Cosmos DB 帳戶。
從左側功能表中選取 [網路]，然後選取 [連線能力] 索引標籤。
您會看到 [最低傳輸層安全性通訊協定] 選項。如果您使用僅支援 TLS 1.2 的 API 種類，則會發現此選項已停用。否則，您只要按一下所需的 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 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

共用方式為