Delen via

Afdwingen van minimale TLS-versies in Azure Cosmos DB

  • Artikel

VAN TOEPASSING OP: NoSQL MongoDB Cassandra Gremlin Tafel

In dit artikel wordt beschreven hoe u een minimale versie van het TLS-protocol afdwingt voor uw Cosmos DB-account met behulp van een selfservice-API.

Hoe minimale AFdwinging van TLS-versies werkt in Azure Cosmos DB

Vanwege de multitenant karakter van Cosmos DB is de service vereist om te voldoen aan de toegangs- en beveiligingsbehoeften van elke gebruiker. Om dit te bereiken, dwingt Cosmos DB minimale TLS-protocollen af op de toepassingslaag en niet lagere lagen in de netwerkstack waar TLS werkt. Deze afdwinging vindt plaats op elke geverifieerde aanvraag voor een specifiek databaseaccount, volgens de instellingen die zijn ingesteld voor dat account door de klant.

De minimale servicebrede geaccepteerde versie is TLS 1.0. Deze selectie kan per account worden gewijzigd, zoals beschreven in de volgende sectie.

De minimale TLS-versie instellen voor mijn Cosmos DB-databaseaccount

Vanaf de API-versie 2022-11-15 van de Azure Cosmos DB-resourceprovider-API wordt er een nieuwe eigenschap weergegeven voor elk Cosmos DB-databaseaccount met de naam minimalTlsVersion. Er wordt een van de volgende waarden geaccepteerd:

  • Tls voor het instellen van de minimale versie op TLS 1.0.
  • Tls11 voor het instellen van de minimumversie op TLS 1.1.
  • Tls12 voor het instellen van de minimale versie op TLS 1.2.

De standaardwaarde voor nieuwe accounts is Tls12.

Belangrijk

Vanaf 31 augustus 2025 moeten alle Cosmos DB-databaseaccounts Transport Layer Security (TLS) 1.2 of hoger gebruiken, omdat ondersteuning voor TLS 1.0 en 1.1 wordt stopgezet.

Minimaal TLS-protocol instellen in Azure Cosmos DB met behulp van de portal

Deze selfservicefunctie is beschikbaar in de portal tijdens het maken en bewerken van een account. Azure Cosmos DB-accounts dwingen het TLS 1.2-protocol af. Azure Cosmos DB ondersteunt echter ook de volgende TLS-protocollen, afhankelijk van het type API dat is geselecteerd.

  • MongoDB: TLS 1.2

  • Cassandra: TLS 1.2

  • Tabel, SQL en Graph: TLS 1.0, TLS 1.1 en TLS 1.2

Stappen voor het instellen van minimaal TLS-protocol tijdens het maken van een account

Als u een API-type gebruikt dat alleen TLS 1.2 ondersteunt, ziet u op het tabblad Netwerken onderaan het TLS-protocol dat is uitgeschakeld.

Schermopname van API-type dat alleen TLS 1.2 ondersteunt.

Als u een API-type gebruikt dat meerdere TLS-protocollen accepteert, kunt u naar het tabblad Netwerken navigeren en is de optie Minimum Transport Layer Security Protocol beschikbaar. U kunt het geselecteerde protocol wijzigen door op de vervolgkeuzelijst te klikken en het gewenste protocol te selecteren.

Schermopname van API-type dat meerdere TLS-protocollen accepteert.

Nadat u uw account hebt ingesteld, kunt u controleren op het tabblad Controleren en maken, onderaan in de sectie Netwerken, dat het geselecteerde TLS-protocol is ingesteld zoals u hebt opgegeven.

Schermopname van het geselecteerde TLS-protocol is ingesteld zoals u hebt opgegeven.

Stappen voor het instellen van het minimale TLS-protocol tijdens het bewerken van een account

  1. Navigeer naar uw Azure Cosmos DB-account in Azure Portal.

  2. Selecteer Netwerken in het linkermenu en selecteer vervolgens het tabblad Connectiviteit.

  3. U vindt de optie Minimum Transport Layer Security Protocol. Als u een API-type gebruikt dat alleen TLS 1.2 ondersteunt, ziet u dat deze optie is uitgeschakeld. Anders kunt u het gewenste TLS-protocol selecteren door erop te klikken.

Schermopname van de optie minimale transportlaagbeveiligingsprotocol.

  1. Klik op Opslaan zodra u het TLS-protocol hebt gewijzigd.

Schermopname van opslaan na wijziging.

  1. Zodra deze is opgeslagen, ontvangt u een melding dat het is gelukt. Het kan nog wel 15 minuten duren voordat deze wijziging van kracht wordt nadat de configuratie-update is voltooid.

Schermopname van geslaagde melding.

Instellen via Azure CLI

Als u wilt instellen met behulp van Azure CLI, gebruikt u de volgende opdracht:

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

Instellen via Azure PowerShell

Als u wilt instellen met Behulp van Azure PowerShell, gebruikt u de volgende opdracht:

$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

Instellen via ARM-sjabloon

Als u deze eigenschap wilt instellen met behulp van een ARM-sjabloon, werkt u uw bestaande sjabloon bij of exporteert u een nieuwe sjabloon voor uw huidige implementatie en voegt u deze vervolgens toe "minimalTlsVersion" aan de eigenschappen voor de databaseAccounts resources, met de gewenste minimale TLS-versiewaarde. Hier vindt u een eenvoudig voorbeeld van een Azure Resource Manager-sjabloon met deze eigenschapsinstelling, met behulp van een 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')]",
      }
    }
}

Belangrijk

Zorg ervoor dat u de andere eigenschappen voor uw account en onderliggende resources opneemt wanneer u deze eigenschap opnieuw implementeert. Implementeer deze sjabloon niet zoals deze is, anders worden al uw accounteigenschappen opnieuw ingesteld.

Voor nieuwe accounts

U kunt accounts maken met de minimalTlsVersion eigenschap die is ingesteld met behulp van de bovenstaande ARM-sjabloon of door de PATCH-methode te wijzigen in een PUT in Azure CLI of Azure PowerShell. Zorg ervoor dat u de andere eigenschappen voor uw account opneemt.

Belangrijk

Als het account bestaat en de minimalTlsVersion eigenschap wordt weggelaten in een PUT-aanvraag, wordt de eigenschap opnieuw ingesteld op de standaardwaarde, te beginnen met de API-versie 2022-11-15.

Minimale afdwinging van TLS-versies controleren

Omdat Cosmos DB de minimale TLS-versie afdwingt op de toepassingslaag, zijn conventionele TLS-scanners die controleren of handshakes worden geaccepteerd door de service voor een specifieke TLS-versie onbetrouwbaar om afdwinging in Cosmos DB te testen. Raadpleeg het officiële opensource cosmos-tls-scannerhulpprogramma om afdwinging te controleren.

U kunt ook de huidige waarde van de minimalTlsVersion eigenschap ophalen met behulp van Azure CLI of Azure PowerShell.

Huidige waarde ophalen via Azure CLI

Voer de opdracht uit om de huidige waarde van de eigenschap op te halen met behulp van 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

Huidige waarde ophalen via Azure PowerShell

Voer de opdracht uit om de huidige waarde van de eigenschap op te halen met behulp van Azure PowerShell:

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