Dela via

Självbetjäning av lägsta TLS-version i Azure Cosmos DB

  • Artikel

GÄLLER FÖR: NoSQL MongoDB Kassandra Gremlin Bord

I den här artikeln beskrivs hur du framtvingar en lägsta version av TLS-protokollet för ditt Cosmos DB-konto med hjälp av ett självbetjänings-API.

Så här fungerar lägsta TLS-versionstillämpning i Azure Cosmos DB

På grund av Cosmos DB:s egenskaper för flera klientorganisationer krävs tjänsten för att uppfylla åtkomst- och säkerhetsbehoven för varje användare. För att uppnå detta framtvingar Cosmos DB lägsta TLS-protokoll på programlagret och inte lägre lager i nätverksstacken där TLS fungerar. Den här tillämpningen sker på alla autentiserade begäranden till ett specifikt databaskonto, enligt de inställningar som kunden har angett för det kontot.

Den lägsta tjänstomfattande godkända versionen är TLS 1.0. Det här valet kan ändras per konto, enligt beskrivningen i följande avsnitt.

Så här anger du den lägsta TLS-versionen för mitt Cosmos DB-databaskonto

Från och med 2022-11-15 API-versionen av Azure Cosmos DB-resursprovider-API:et exponeras en ny egenskap för varje Cosmos DB-databaskonto med namnet minimalTlsVersion. Det accepterar något av följande värden:

  • Tls för att ange den lägsta versionen till TLS 1.0.
  • Tls11 för att ange den lägsta versionen till TLS 1.1.
  • Tls12 för att ange lägsta version till TLS 1.2.

Standardvärdet för nya konton är Tls12.

Viktigt!

Från och med den 31 augusti 2025 måste alla Cosmos DB-databaskonton använda TLS (Transport Layer Security) 1.2 eller senare, eftersom stödet för TLS 1.0 och 1.1 upphör.

Ange minimalt TLS-protokoll i Azure Cosmos DB med hjälp av portalen

Den här självbetjäningsfunktionen är tillgänglig i portalen när du skapar och redigerar ett konto. Azure Cosmos DB-konton tillämpar TLS 1.2-protokollet. Azure Cosmos DB stöder dock även följande TLS-protokoll beroende på vilken API-typ som valts.

  • MongoDB: TLS 1.2

  • Cassandra: TLS 1.2

  • Tabell, SQL och Graph: TLS 1.0, TLS 1.1 och TLS 1.2

Steg för att ange minimalt TLS-protokoll när du skapar ett konto

Om du använder en API-typ som endast stöder TLS 1.2 ser du att TLS-protokollet är inaktiverat på fliken Nätverk längst ned.

Skärmbild av API Kind som endast stöder TLS 1.2.

Om du använder en API-typ som accepterar flera TLS-protokoll kan du navigera till fliken Nätverk och alternativet Minsta transportnivåsäkerhetsprotokoll är tillgängligt. Du kan ändra det valda protokollet genom att bara klicka på listrutan och välja önskat protokoll.

Skärmbild av API Kind som accepterar flera TLS-protokoll.

När du har konfigurerat ditt konto kan du granska på fliken Granska + skapa längst ned i avsnittet Nätverk att det valda TLS-protokollet har angetts som du angav.

Skärmbild av valt TLS-protokoll har angetts som du angav.

Steg för att ange minimalt TLS-protokoll vid redigering av ett konto

  1. Gå till ditt Azure Cosmos DB-konto på Azure Portal.

  2. Välj Nätverk på den vänstra menyn och välj sedan fliken Anslutning.

  3. Du hittar alternativet Minsta transportnivåsäkerhetsprotokoll. Om du använder en API Kind som endast stöder TLS 1.2 ser du att det här alternativet är inaktiverat. Annars kan du välja önskat TLS-protokoll genom att bara klicka på det.

Skärmbild av minsta säkerhetsprotokollalternativ för transportskikt.

  1. Klicka på Spara när du har ändrat TLS-protokollet.

Skärmbild av spara efter ändring.

  1. När den har sparats får du ett meddelande om att åtgärden har slutförts. Den här ändringen kan dock ta upp till 15 minuter att börja gälla när konfigurationsuppdateringen har slutförts.

Skärmbild av meddelande om lyckat resultat.

Ange via Azure CLI

Om du vill ange med Azure CLI använder du kommandot:

rg="myresourcegroup"
dbName="mycosmosdbaccount"
minimalTlsVersion="Tls12"
az cosmosdb update -n $dbName -g $rg --minimal-tls-version $minimalTlsVersion

Ange via Azure PowerShell

Om du vill ange med Azure PowerShell använder du kommandot:

$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

Ange via ARM-mall

Om du vill ange den här egenskapen med hjälp av en ARM-mall uppdaterar du din befintliga mall eller exporterar en ny mall för den aktuella distributionen och lägger sedan till "minimalTlsVersion" egenskaperna för databaseAccounts resurserna med önskat lägsta TLS-versionsvärde. Här visas ett grundläggande exempel på en Azure Resource Manager-mall med den här egenskapsinställningen med hjälp av en parameter.

{
    {
      "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')]",
      }
    }
}

Viktigt!

Se till att du inkluderar de andra egenskaperna för ditt konto och underordnade resurser när du distribuerar om med den här egenskapen. Distribuera inte den här mallen som den är, annars återställs alla dina kontoegenskaper.

För nya konton

Du kan skapa konton med egenskapen minimalTlsVersion som angetts med hjälp av ARM-mallen ovan eller genom att ändra METODEN PATCH till en PUT på Antingen Azure CLI eller Azure PowerShell. Se till att inkludera de andra egenskaperna för ditt konto.

Viktigt!

Om kontot finns och minimalTlsVersion egenskapen utelämnas i en PUT-begäran återställs egenskapen till standardvärdet från och med API-versionen 2022-11-15.

Så här verifierar du lägsta TLS-versionstillämpning

Eftersom Cosmos DB tillämpar den lägsta TLS-versionen på programskiktet är konventionella TLS-skannrar som kontrollerar om handskakningar accepteras av tjänsten för en specifik TLS-version otillförlitliga för att testa tillämpningen i Cosmos DB. Om du vill verifiera tillämpningen läser du det officiella cosmos-tls-scanner-verktyget med öppen källkod.

Du kan också hämta det aktuella värdet för minimalTlsVersion egenskapen med hjälp av Azure CLI eller Azure PowerShell.

Hämta aktuellt värde via Azure CLI

Kör kommandot för att hämta det aktuella värdet för egenskapen med hjälp av 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

Hämta aktuellt värde via Azure PowerShell

Kör kommandot för att hämta det aktuella värdet för egenskapen med hjälp av Azure PowerShell:

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