Erzwingen von TLS-Mindestversionen in Azure Cosmos DB als Self-Service

GILT FÜR: NoSQL MongoDB Cassandra Gremlin Tabelle

In diesem Artikel wird erläutert, wie Sie mithilfe einer Self-Service-API eine Mindestversion des TLS-Protokolls für Ihr Cosmos DB-Konto erzwingen.

Funktionsweise der Erzwingung der TLS-Mindestversion in Azure Cosmos DB

Aufgrund der mehrinstanzenfähigen Natur von Cosmos DB ist der Dienst erforderlich, um die Zugriffs- und Sicherheitsanforderungen jedes Benutzers zu erfüllen. Um dies zu erreichen, erzwingt Cosmos DB TLS-Mindestprotokolle auf der Anwendungsebene und nicht auf niedrigeren Ebenen im Netzwerkstapel, in dem TLS betrieben wird. Diese Erzwingung erfolgt bei jeder authentifizierten Anforderung an ein bestimmtes Datenbankkonto gemäß den Einstellungen, die der Kunde für dieses Konto festgelegt hat.

Die dienstweit akzeptierte Mindestversion ist TLS 1.0. Diese Auswahl kann auf Kontobasis geändert werden, wie im folgenden Abschnitt erläutert.

Festlegen der TLS-Mindestversion für mein Cosmos DB-Datenbankkonto

Ab der API-Version 2022-11-15 der Azure Cosmos DB-Ressourcenanbieter-API wird eine neue Eigenschaft für jedes Cosmos DB-Datenbankkonto mit dem Namen minimalTlsVersion verfügbar gemacht. Einer der folgenden Werte wird akzeptiert:

• Tls zum Festlegen der Mindestversion auf TLS 1.0.
• Tls11 zum Festlegen der Mindestversion auf TLS 1.1.
• Tls12 zum Festlegen der Mindestversion auf TLS 1.2.

Der Standardwert für neue Konten lautet Tls12.

Wichtig

Ab dem 31. August 2025 müssen alle Cosmos DB-Datenbankkonten TLS 1.2 (Transport Layer Security) oder höher verwenden, da die Unterstützung für TLS 1.0 und 1.1 eingestellt wird.

Festlegen des minimalen TLS-Protokolls in Azure Cosmos DB über das Portal

Dieses Self-Service-Feature ist im Portal beim Erstellen und Bearbeiten eines Kontos verfügbar. Azure Cosmos DB-Konten erzwingen das TLS 1.2-Protokoll. Azure Cosmos DB unterstützt jedoch je nach ausgewählter API-Art auch die folgenden TLS-Protokolle.

• MongoDB: TLS 1.2

• Cassandra: TLS 1.2

• Tabelle, SQL und Graph: TLS 1.0, TLS 1.1 und TLS 1.2

Schritte zum Festlegen des minimalen TLS-Protokolls beim Erstellen eines Kontos

Wenn Sie eine API-Art verwenden, die nur TLS 1.2 unterstützt, werden Sie auf der Registerkarte „Netzwerk“ unten das TLS-Protokoll deaktiviert sehen.

Wenn Sie eine API-Art verwenden, die mehrere TLS-Protokolle akzeptiert, können Sie zur Registerkarte „Netzwerk“ navigieren, und die Option „Minimum Transport Layer Security Protocol“ ist verfügbar. Sie können das ausgewählte Protokoll ändern, indem Sie einfach auf die Dropdownliste klicken und das gewünschte Protokoll auswählen.

Nachdem Sie Ihr Konto eingerichtet haben, können Sie auf der Registerkarte „Überprüfen + Erstellen“ unten im Abschnitt „Netzwerk“ überprüfen, dass das ausgewählte TLS-Protokoll wie angegeben festgelegt ist.

Schritte zum Festlegen des minimalen TLS-Protokolls beim Bearbeiten eines Kontos

1. Navigieren Sie im Azure-Portal zu Ihrem Azure Cosmos DB-Konto.

2. Wählen Sie im linken Menü „Netzwerk“ und dann die Registerkarte „Konnektivität“ aus.

3. Sie sehen die Option „Minimum Transport Layer Security Protocol“. Wenn Sie eine API-Art verwenden, die nur TLS 1.2 unterstützt, werden Sie feststellen, dass diese Option deaktiviert ist. Andernfalls können Sie das gewünschte TLS-Protokoll auswählen, indem Sie einfach darauf klicken.

4. Klicken Sie auf „Speichern“, nachdem Sie das TLS-Protokoll geändert haben.

5. Nach dem Speichern erhalten Sie eine Erfolgsbenachrichtigung. Dennoch kann es bis zu 15 Minuten dauern, bis diese Änderung wirksam wird, nachdem das Konfigurationsupdate abgeschlossen ist.

Festlegen über die Azure-Befehlszeilenschnittstelle

Verwenden Sie zum Festlegen über die Azure CLI den Befehl:

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

Festlegen über Azure PowerShell

Verwenden Sie zum Festlegen über Azure PowerShell den Befehl:

$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

Festlegen per ARM-Vorlage

Wenn Sie diese Eigenschaft mithilfe einer ARM-Vorlage festlegen möchten, aktualisieren Sie Ihre vorhandene Vorlage, oder exportieren Sie eine neue Vorlage für Ihre aktuelle Bereitstellung. Fügen Sie dann "minimalTlsVersion" mit dem gewünschten Wert für die TLS-Mindestversion zu den Eigenschaften für die databaseAccounts-Ressourcen hinzu. Hier sehen Sie ein einfaches Beispiel für eine Azure Resource Manager-Vorlage mit dieser Eigenschaftseinstellung, die einen Parameter verwendet.

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

Wichtig

Schließen Sie bei der erneuten Bereitstellung mit dieser Eigenschaft auch die anderen Eigenschaften für Ihr Konto und Ihre untergeordneten Ressourcen mit ein. Wenn Sie diese Vorlage unverändert bereitstellen, werden alle Ihre Kontoeigenschaften zurückgesetzt.

Für neue Konten

Sie können Konten erstellen, deren minimalTlsVersion-Eigenschaft festgelegt ist, indem Sie die oben genannte ARM-Vorlage verwenden oder die PATCH-Methode in einen PUT-Wert ändern, entweder in der Azure CLI oder in Azure PowerShell. Stellen Sie sicher, dass Sie die anderen Eigenschaften für Ihr Konto einschließen.

Wichtig

Wenn das Konto vorhanden ist und die minimalTlsVersion-Eigenschaft in einer PUT-Anforderung ausgelassen wird, wird die Eigenschaft auf ihren Standardwert zurückgesetzt, beginnend mit der API-Version 2022-11-15.

Überprüfen der Erzwingung der TLS-Mindestversion

Da Cosmos DB die TLS-Mindestversion auf Anwendungsebene erzwingt, sind herkömmliche TLS-Scanner, die überprüfen, ob Handshakes vom Dienst für eine bestimmte TLS-Version akzeptiert werden, zum Testen der Erzwingung in Cosmos DB unzuverlässig. Informationen zum Überprüfen der Erzwingung finden Sie unter dem offiziellen Open-Source-Tool „cosmos-tls-scanner“.

Sie können den aktuellen Wert der minimalTlsVersion-Eigenschaft auch mithilfe der Azure CLI oder mit Azure PowerShell abrufen.

Abrufen des aktuellen Werts über die Azure CLI

Führen Sie den Befehl aus, um den aktuellen Wert der Eigenschaft mithilfe der Azure CLI abzurufen:

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

Abrufen des aktuellen Werts über Azure PowerShell

Führen Sie den Befehl aus, um den aktuellen Wert der Eigenschaft mithilfe von Azure PowerShell abzurufen:

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