Konfigurieren von kundenseitig verwalteten Schlüsseln für Ihr Azure Cosmos DB-Konto mit Azure Key Vault

Artikel
08/15/2024

GILT FÜR: NoSQL MongoDB Cassandra Gremlin Tabelle

Die in Ihrem Azure Cosmos DB-Konto gespeicherten Daten werden automatisch und nahtlos mit von Microsoft verwalteten Schlüsseln (dienstseitig verwaltete Schlüssel) verschlüsselt. Optional können Sie eine zweite Verschlüsselungsebene mit von Ihnen verwalteten Schlüsseln (Customer-managed keys oder CMK) hinzufügen.

Abbildung: Verschlüsselungsschicht um Kundendaten

Sie müssen vom Kunden verwaltete Schlüssel in Azure Key Vault speichern und einen Schlüssel für jedes Azure Cosmos DB-Konto bereitstellen, für das vom Kunden verwalteten Schlüssel aktiviert sind. Dieser Schlüssel wird zum Verschlüsseln aller in diesem Konto gespeicherten Daten verwendet.

Hinweis

Wenn Sie kundenverwaltete Schlüssel für Ihre vorhandenen Azure Cosmos DB-Konten aktivieren möchten, können Sie hier auf den Link verweisen, um weitere Details zu erhalten

Warnung

Die folgenden Feldnamen sind für Cassandra-API-Tabellen in Konten reserviert, die kundenseitig verwaltete Schlüssel verwenden:

id
ttl
_ts
_etag
_rid
_self
_attachments
_epk

Wenn kundenseitig verwaltete Schlüssel nicht aktiviert sind, werden nur Feldnamen reserviert, die mit __sys_ beginnen.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.

Registrieren des Azure Cosmos DB-Ressourcenanbieters

Wenn der Ressourcenanbieter Microsoft.DocumentDB noch nicht registriert ist, sollten Sie diesen Anbieter als Erstes registrieren.

Melden Sie sich beim Azure-Portal an, navigieren Sie zu Ihrem Azure-Abonnement, und wählen Sie auf der Registerkarte Einstellungen die Option Ressourcenanbieter aus:
Suchen Sie nach dem Ressourcenanbieter Microsoft.DocumentDB. Überprüfen Sie, ob der Ressourcenanbieter bereits als registriert gekennzeichnet ist. Wenn dies nicht der Fall ist, wählen Sie den Ressourcenanbieter aus, und wählen Sie dann Registrieren aus:

Konfigurieren Ihrer Azure Key Vault-Instanz

Wichtig

Ihre Azure Key Vault-Instanz muss über den öffentlichen Netzwerkzugriff zugänglich sein oder vertrauenswürdige Microsoft-Dienste zulassen, um dessen Firewall zu umgehen. Eine Instanz, auf die ausschließlich über private Endpunkte zugegriffen werden kann, kann nicht zum Hosten Ihrer kundenseitig verwalteten Schlüssel verwendet werden.

Wenn Sie kundenseitig verwaltete Schlüssel mit Azure Cosmos DB verwenden, müssen Sie zwei Eigenschaften für die Azure Key Vault-Instanz festlegen, die Sie zum Hosten Ihrer Verschlüsselungsschlüssel verwenden möchten: Vorläufiges Löschen und Löschschutz.

Wenn Sie eine neue Azure Key Vault-Instanz erstellen, aktivieren Sie diese Eigenschaften während der Erstellung:
Bei Verwendung einer vorhandenen Azure Key Vault-Instanz können Sie überprüfen, ob diese Eigenschaften aktiviert sind, indem Sie sich im Azure-Portal den Abschnitt Eigenschaften ansehen. Ist eine dieser Eigenschaften nicht aktiviert, finden Sie in den Abschnitten „Aktivieren des vorläufigen Löschens“ und „Aktivieren des Bereinigungsschutzes“ in einem der folgenden Artikel weitere Informationen:
- Verwenden des vorläufigen Löschens mit PowerShell
- Verwenden des vorläufigen Löschens mit Azure CLI

Auswählen des bevorzugten Sicherheitsmodells

Sobald Bereinigungsschutz und vorläufiges Löschen aktiviert sind, können Sie auf der Registerkarte „Zugriffsrichtlinie“ Ihr bevorzugtes Berechtigungsmodell für die Verwendung auswählen. Zugriffsrichtlinien sind standardmäßig festgelegt, aber auch die rollenbasierte Zugriffssteuerung in Azure wird unterstützt.

Die erforderlichen Berechtigungen müssen erteilt werden, damit Cosmos DB Ihren Verschlüsselungsschlüssel verwenden kann. Dieser Schritt variiert je nachdem, ob Azure Key Vault Zugriffsrichtlinien oder die rollenbasierte Zugriffssteuerung verwendet.

Hinweis

Es ist wichtig zu beachten, dass nur jeweils ein Sicherheitsmodell aktiv sein kann, sodass es nicht erforderlich ist, ein Seeding für die rollenbasierte Zugriffssteuerung auszuführen, wenn Azure Key Vault für die Verwendung von Zugriffsrichtlinien festgelegt ist (und umgekehrt).

Hinzufügen einer Zugriffsrichtlinie

Verwenden Sie bei dieser Variante den Azure Cosmos DB-Prinzipal, um eine Zugriffsrichtlinie mit den entsprechenden Berechtigungen zu erstellen.

Navigieren Sie im Azure-Portal zu der Azure Key Vault-Instanz, die Sie zum Hosten Ihrer Verschlüsselungsschlüssel verwenden möchten. Wählen Sie im linken Menü die Option Zugriffsrichtlinien aus.
Wählen Sie + Zugriffsrichtlinie hinzufügen aus.
Wählen Sie im Dropdownmenü Schlüsselberechtigungen die Berechtigungen Abrufen, Schlüssel entpacken und Schlüssel packen aus:
Wählen Sie unter Prinzipal auswählen die Option Nichts ausgewählt aus.
Suchen Sie nach dem Azure Cosmos DB-Prinzipal, und wählen Sie ihn aus (um die Suche zu erleichtern, können Sie auch nach der Anwendungs-ID suchen: 00001111-aaaa-2222-bbbb-3333cccc4444 für eine beliebige Azure-Region mit Ausnahme von Azure Government-Regionen, bei denen die Anwendungs-ID 11112222-bbbb-3333-cccc-4444dddd5555 lautet).

Tipp

So wird die Erstanbieteridentität von Azure Cosmos DB in Ihrer Azure Key Vault-Zugriffsrichtlinie registriert. Wenn der Prinzipal Azure Cosmos DB nicht in der Liste aufgeführt ist, müssen Sie möglicherweise den Ressourcenanbieter Microsoft.DocumentDB erneut registrieren.
Wählen Sie im unteren Bereich Auswählen aus.
Wählen Sie Hinzufügen aus, um die neue Zugriffsrichtlinie hinzuzufügen.
Wählen Sie Speichern in der Key Vault-Instanz aus, um alle Änderungen zu speichern.

Hinzufügen von Rollen für die rollenbasierte Zugriffssteuerung

Navigieren Sie im Azure-Portal zu der Azure Key Vault-Instanz, die Sie zum Hosten Ihrer Verschlüsselungsschlüssel verwenden möchten. Wählen Sie im linken Menü Zugriffssteuerung (IAM) und dann Zugriff auf diese Ressource gewähren aus.
Suchen Sie die Rolle Key Vault-Administrator, und weisen Sie sie sich selbst zu. Für die Zuweisung müssen Sie zuerst in der Liste nach dem Rollennamen suchen und dann auf die Registerkarte Mitglieder klicken. Wählen Sie auf der Registerkarte das Optionsfeld „Benutzer, Gruppe oder Dienstprinzipal“ aus, und suchen Sie dann Ihr Azure-Konto. Nachdem das Konto ausgewählt wurde, kann die Rolle zugewiesen werden.
Anschließend müssen dem Prinzipal von Cosmos DB die erforderlichen Berechtigungen zugewiesen werden. Navigieren Sie also wie bei der letzten Rollenzuweisung zur Zuweisungsseite, suchen Sie aber dieses Mal nach der Rolle Kryptografiedienstverschlüsselung für Schlüsseltresore, und suchen Sie auf der Registerkarte „Mitglieder“ nach dem Prinzipal von Cosmos DB. Um den Prinzipal zu ermitteln, suchen Sie nach dem Prinzipal Azure Cosmos DB, und wählen Sie ihn aus.

Wichtig

In der Azure Government-Region lautet die Anwendungs-ID 11112222-bbbb-3333-cccc-4444dddd5555.
Wählen Sie „Überprüfen + zuweisen“ aus, und die Rolle wird Cosmos DB zugewiesen.

Überprüfen, ob die Rollen richtig festgelegt wurden

Überprüfen Sie als Nächstes auf der Seite „Zugriffssteuerung“, ob alle Rollen ordnungsgemäß konfiguriert wurden.

Nachdem die Rollen zugewiesen wurden, wählen Sie auf der Seite „Zugriffssteuerung (IAM)“ die Option Zugriff auf diese Ressource anzeigen aus, um zu überprüfen, ob alles ordnungsgemäß festgelegt wurde.
Legen Sie auf der Seite den Bereich auf diese Ressource fest, und vergewissern Sie sich, dass Sie über die Rolle „Key Vault-Administrator“ verfügen und der Cosmos DB-Prinzipal über die Rolle „Kryptografiedienstverschlüsselung für Schlüsseltresore“ verfügt.

Generieren eines Schlüssels in Azure Key Vault

Erstellen Sie hier mithilfe von Azure Key Vault einen neuen Schlüssel, und rufen Sie den eindeutigen Bezeichner ab.

Navigieren Sie im Azure-Portal zu der Azure Key Vault-Instanz, die Sie zum Hosten Ihrer Verschlüsselungsschlüssel verwenden möchten. Wählen Sie dann im linken Menü die Option Schlüssel aus:
Wählen Sie Generieren/Importieren aus, geben Sie einen Namen für den neuen Schlüssel an, und wählen Sie eine RSA-Schlüsselgröße aus. Es wird eine Größe von mindestens 3072 empfohlen, da diese Größe die höchste Sicherheit bietet. Wählen Sie anschließend Erstellen aus:
Tipp

Alternativ können Sie mit der Azure CLI einen Schlüssel zu generieren mit:
```
az keyvault key create \
    --vault-name <name-of-key-vault> \
    --name <name-of-key>
```
Weitere Informationen zum Verwalten eines Schlüsseltresors mit der Azure CLI finden Sie unter Verwalten von Azure Key Vault mit der Azure CLI.
Wählen Sie nach der Schlüsselerstellung den neu erstellten Schlüssel und dann seine aktuelle Version aus.
Kopieren Sie den Schlüsselbezeichner des Schlüssels mit Ausnahme des Teils nach dem letzten Schrägstrich:

Erstellen eines neuen Azure Cosmos DB-Kontos

Erstellen Sie mithilfe des Azure-Portals oder der Azure CLI ein neues Azure Cosmos DB-Konto.

Wählen Sie beim Erstellen eines neuen Azure Cosmos DB-Kontos im Azure-Portal im Schritt Verschlüsselung die Option Vom Kunden verwalteter Schlüssel aus. Fügen Sie in das Feld Schlüssel-URI den URI/Schlüsselbezeichner des Azure Key Vault-Schlüssels ein, den Sie im vorherigen Schritt kopiert haben:

Berücksichtigen Sie Folgendes, wenn Sie ein neues Azure Cosmos DB-Konto mit PowerShell erstellen:

Übergeben Sie den zuvor kopierten URI des Azure Key Vault-Schlüssels unter der Eigenschaft keyVaultKeyUri im PropertyObject.
Verwenden Sie mindestens 2019-12-12 als API-Version.

Wichtig

Sie müssen die Eigenschaft locations explizit festlegen, damit das Konto erfolgreich mit kundenseitig verwalteten Schlüsseln erstellt werden kann.

# Variable for resource group name
$RESOURCE_GROUP_NAME = "<resource-group-name>"

# Variable for location
$LOCATION = "<azure-region>"

# Variable for account name
$ACCOUNT_NAME = "<globally-unique-account-name>"

# Variable for key URI in the key vault
$KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

$parameters = @{
    ResourceType = "Microsoft.DocumentDb/databaseAccounts"
    ApiVersion = "2019-12-12"
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Location = $LOCATION 
    Name = $ACCOUNT_NAME 
    PropertyObject = @{
        databaseAccountOfferType = "Standard"
        locations = @(
            @{ 
                locationName = $LOCATION 
                failoverPriority = 0
            }
        )
        keyVaultKeyUri = $KEY_VAULT_KEY_URI
    }
}
New-AzResource @parameters

Nach der Erstellung des Kontos können Sie überprüfen, ob kundenseitig verwaltete Schlüssel aktiviert wurden, indem Sie den URI des Azure Key Vault-Schlüssels abrufen:

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    ResourceType = "Microsoft.DocumentDb/databaseAccounts"
}
Get-AzResource @parameters
    | Select-Object -ExpandProperty Properties
    | Select-Object -ExpandProperty keyVaultKeyUri

Berücksichtigen Sie Folgendes, wenn Sie ein neues Azure Cosmos DB-Konto anhand einer Azure Resource Manager-Vorlage erstellen:

Übergeben Sie den zuvor kopierten URI des Azure Key Vault-Schlüssels unter der Eigenschaft keyVaultKeyUri im Objekt properties.
Verwenden Sie mindestens 2019-12-12 als API-Version.

Wichtig

Sie müssen die Eigenschaft locations explizit festlegen, damit das Konto erfolgreich mit kundenseitig verwalteten Schlüsseln erstellt werden kann.

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "accountName": {
      "type": "string"
    },
    "location": {
      "type": "string"
    },
    "keyVaultKeyUri": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "name": "[parameters('accountName')]",
      "apiVersion": "2019-12-12",
      "kind": "GlobalDocumentDB",
      "location": "[parameters('location')]",
      "properties": {
        "locations": [
          {
            "locationName": "[parameters('location')]",
            "failoverPriority": 0,
            "isZoneRedundant": false
          }
        ],
        "databaseAccountOfferType": "Standard",
        "keyVaultKeyUri": "[parameters('keyVaultKeyUri')]"
      }
    }
  ]
}

Stellen Sie die Vorlage mithilfe des folgenden PowerShell-Skripts bereit:

# Variable for resource group name
$RESOURCE_GROUP_NAME = "<resource-group-name>"

# Variable for location
$LOCATION = "<azure-region>"

# Variable for account name
$ACCOUNT_NAME = "<globally-unique-account-name>"

# Variable for key URI in the key vault
$KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    TemplateFile = "deploy.json"
    accountName = $ACCOUNT_NAME
    location = $LOCATION
    keyVaultKeyUri = $KEY_VAULT_KEY_URI
}
New-AzResourceGroupDeployment @parameters

Wenn Sie ein neues Azure Cosmos DB-Konto über die Azure-Befehlszeilenschnittstelle erstellen, übergeben Sie den URI des Azure Key Vault-Schlüssels, den Sie zuvor unter dem Parameter --key-uri kopiert haben.

# Variable for resource group name
resourceGroupName="<resource-group-name>"

# Variable for location
location="<azure-region>"

# Variable for account name
accountName="<globally-unique-account-name>"

# Variable for key URI in the key vault
keyVaultKeyUri="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location \
    --key-uri $keyVaultKeyUri

Nach der Erstellung des Kontos können Sie überprüfen, ob kundenseitig verwaltete Schlüssel aktiviert wurden, indem Sie den URI des Azure Key Vault-Schlüssels abrufen:

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "keyVaultKeyUri"

Wichtig

Je nach Netzwerkkonfiguration müssen Sie möglicherweise den Zugriff auf Azure Cosmos DB von anderen Azure-Diensten aus zulassen.

Verwenden einer verwalteten Identität in der Azure Key Vault-Zugriffsrichtlinie

Diese Zugriffsrichtlinie stellt sicher, dass Ihr Azure Cosmos DB-Konto auf Ihre Verschlüsselungsschlüssel zugreifen kann. Die Zugriffsrichtlinie wird durch Zuweisen des Zugriffs auf eine bestimmte Microsoft Entra-Identität implementiert. Zwei Typen von Identitäten werden unterstützt:

Mit der Erstanbieteridentität von Azure Cosmos DB können Sie Zugriff auf den Azure Cosmos DB-Dienst gewähren.
Mit der verwalteten Identität Ihres Azure Cosmos DB-Kontos können Sie speziell Zugriff auf Ihr Konto gewähren.

Sie können ARM-Vorlagen verwenden, um einer Zugriffsrichtlinie eine verwaltete Identität zuzuweisen.

Da eine systemseitig zugewiesene verwaltete Identität nur nach der Erstellung Ihres Kontos abgerufen werden kann, müssen Sie Ihr Konto noch zunächst mit der Erstanbieteridentität erstellen. Führen Sie anschließend Folgendes durch:

Wenn die systemseitig zugewiesene verwaltete Identität nicht während der Kontoerstellung konfiguriert wurde, aktivieren Sie eine systemseitig zugewiesene verwaltete Identität in Ihrem Konto und kopieren die zugewiesene principalId.
Fügen Sie Ihrem Azure Key Vault-Konto die entsprechenden Berechtigungen hinzu, wie zuvor beschrieben. Verwenden Sie statt des Cosmos DB-Prinzipals die Prinzipal-ID (principalId), die Sie anstelle der Erstanbieteridentität von Azure Cosmos DB kopiert haben.
Aktualisieren Sie Ihr Azure Cosmos DB-Konto, um anzugeben, dass Sie die vom System zugewiesene verwaltete Identität beim Zugriff auf Ihre Verschlüsselungsschlüssel in Azure Key Vault verwenden möchten.
```
{
  "type": " Microsoft.DocumentDB/databaseAccounts",
  "properties": {
    "defaultIdentity": "SystemAssignedIdentity",
    // ...
  },
  // ...
}
```
Optional können Sie die Erstanbieteridentität von Azure Cosmos DB aus Ihrer Azure Key Vault-Zugriffsrichtlinie entfernen.

Sie können auch ähnliche Schritte mit einer benutzerseitig zugewiesenen verwalteten Identität ausführen.

Wenn Sie die neue Zugriffsrichtlinie oder Rollenzuweisung in Ihrem Azure Key Vault-Konto erstellen, verwenden Sie die Objekt-ID (Object ID) der verwalteten Identität, die Sie anstelle der Erstanbieteridentität von Azure Cosmos DB verwenden möchten.

Bei der Erstellung Ihres Azure Cosmos DB-Kontos müssen Sie die dem Benutzer zugewiesene verwaltete Identität aktivieren und angeben, dass Sie diese Identität beim Zugriff auf Ihre Verschlüsselungsschlüssel in Azure Key Vault verwenden möchten.

{
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<identity-resource-id>": {}
    }
  },
  // ...
  "properties": {
    "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>",
    "keyVaultKeyUri": "<key-vault-key-uri>"
    // ...
  }
}

Sie können die Azure CLI verwenden, um einer Zugriffsrichtlinie eine verwaltete Identität zuzuweisen.

Wenn die systemseitig zugewiesene verwaltete Identität nicht während der Kontoerstellung konfiguriert wurde, aktivieren Sie eine systemseitig zugewiesene verwaltete Identität in Ihrem Konto und kopieren die zugewiesene principalId.
Fügen Sie Ihrem Azure Key Vault-Konto die entsprechenden Berechtigungen hinzu, wie zuvor beschrieben. Verwenden Sie statt des Cosmos DB-Prinzipals die Prinzipal-ID (principalId), die Sie anstelle der Erstanbieteridentität von Azure Cosmos DB kopiert haben.

Aktualisieren Sie Ihr Azure Cosmos DB-Konto, um anzugeben, dass Sie die vom System zugewiesene verwaltete Identität beim Zugriff auf Ihre Verschlüsselungsschlüssel in Azure Key Vault verwenden möchten.

# Variables for resource group and account names
resourceGroupName="<resource-group-name>"
accountName="<azure-cosmos-db-account-name>"

az cosmosdb update \
    --resource-group $resourceGroupName \
    --name $accountName \
    --default-identity "SystemAssignedIdentity"

Optional können Sie die Erstanbieteridentität von Azure Cosmos DB aus Ihrer Azure Key Vault-Zugriffsrichtlinie entfernen.

Sie können auch ähnliche Schritte mit einer benutzerseitig zugewiesenen verwalteten Identität ausführen.

Wenn Sie die neue Zugriffsrichtlinie oder Rollenzuweisung in Ihrem Azure Key Vault-Konto erstellen, verwenden Sie die Objekt-ID (Object ID) der verwalteten Identität, die Sie anstelle der Erstanbieteridentität von Azure Cosmos DB verwenden möchten.

# Variables for resource group and account name
resourceGroupName="<resource-group-name>"
accountName="<azure-cosmos-db-account-name>"

# Variable for location
location="<azure-region>"

# Variable for key URI in the key vault
keyVaultKeyUri="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

# Variables for identities
identityId="<identity-resource-id>"

az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location \
    --key-uri $keyVaultKeyUri
    --assign-identity $identityId \
    --default-identity "UserAssignedIdentity=$identityId"

Nicht verfügbar

Verwenden von kundenseitig verwalteten Schlüsseln mit fortlaufender Sicherung

Sie können über die Azure CLI oder eine Azure Resource Manager-Vorlage ein Konto für die fortlaufende Sicherung erstellen.

Derzeit wird nur eine benutzerseitig zugewiesene verwaltete Identität zum Erstellen von Konten für die fortlaufende Sicherung unterstützt.

Nachdem das Konto erstellt wurde, können Sie die Identität auf eine systemseitig zugewiesene verwaltete Identität aktualisieren.

Alternativ kann der Benutzer zunächst auch eine Systemidentität mit regelmäßigem Sicherungsmodus erstellen und dann das Konto mithilfe dieser Anweisungen unter Migrieren eines Azure Cosmos DB-Kontos vom zyklischen Sicherungsmodus zum fortlaufenden Sicherungsmodus zum Modus für die fortlaufende Sicherung migrieren.

# Variables for resource group and account name
resourceGroupName="<resource-group-name>"
accountName="<azure-cosmos-db-account-name>"

# Variable for location
location="<azure-region>"

# Variable for key URI in the key vault
keyVaultKeyUri="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

# Variables for identities
identityId="<identity-resource-id>"

az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location \
    --key-uri $keyVaultKeyUri
    --assign-identity $identityId \
    --default-identity "UserAssignedIdentity=$identityId" \
    --backup-policy-type "Continuous"

Berücksichtigen Sie Folgendes, wenn Sie ein neues Azure Cosmos DB-Konto anhand einer Azure Resource Manager-Vorlage erstellen:

Übergeben Sie den zuvor kopierten URI des Azure Key Vault-Schlüssels unter der Eigenschaft keyVaultKeyUri im Objekt properties.
Verwenden Sie als API-Version mindestens 2021-11-15.

Wichtig

Sie müssen die Eigenschaft locations explizit festlegen, damit das Konto erfolgreich mit kundenseitig verwalteten Schlüsseln erstellt werden kann (wie im vorstehenden Beispiel gezeigt).

{
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<identity-resource-id>": {}
    }
  },
  // ...
  "properties": {
    "backupPolicy": {
      "type": "Continuous"
    },
    "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>""keyVaultKeyUri": "<key-vault-key-uri>"
    // ...
  }
}

Nicht verfügbar

Wiederherstellen eines fortlaufenden Kontos, das mit verwalteter Identität konfiguriert ist

In der Wiederherstellungsanforderung ist eine benutzerspezifische Identität erforderlich, da die vom Quellkonto verwaltete Identität (benutzerspezifische und systembezogene Identitäten) nicht automatisch auf das Zieldatenbankkonto übertragen werden kann.

Azure-Befehlszeilenschnittstelle
PowerShell/Azure Resource Manager-Vorlage/Azure-Portal

Verwenden Sie die Azure CLI, um ein fortlaufendes Konto wiederherzustellen, das bereits mit einer systemseitig oder benutzerseitig zugewiesenen verwalteten Identität konfiguriert ist.

Erstellen Sie eine neue benutzerseitig zugewiesene Identität (oder verwenden Sie eine vorhandene Identität) für den Wiederherstellungsvorgang.
Erstellen Sie die neue Zugriffsrichtlinie in Ihrem Azure Key Vault-Konto, wie oben beschrieben, und verwenden Sie die Objekt-ID der verwalteten Identität aus Schritt 1.

Lösen Sie die Wiederherstellung mithilfe der Azure CLI aus:

# Variables for resource group and account names
resourceGroupName="<resource-group-name>"
sourceAccountName="<source-azure-cosmos-db-account-name>"
targetAccountName="<target-azure-cosmos-db-account-name>"

# Variable for location
location="<azure-region>"

# Variables for identities
identityId="<identity-resource-id>"

# Variable for timestamp to restore to
timestamp="<timestamp-in-utc>"

az cosmosdb restore \ 
    --resource-group $resourceGroupName \
    --account-name $sourceAccountName \
    --target-database-account-name $targetAccountName \
    --location $location \
    --restore-timestamp $timestamp \
    --assign-identity $identityId \
    --default-identity "UserAssignedIdentity=$identityId" \

Nach Abschluss der Wiederherstellung verfügt das (wiederhergestellte) Zielkonto über die benutzerseitig zugewiesene Identität. Bei Bedarf kann der Benutzer das Konto für die Verwendung der systemseitig zugewiesenen verwalteten Identität aktualisieren.

Nicht verfügbar

Kundenseitig verwaltete Schlüssel und Mehrfachverschlüsselung

Bei Verwendung von kundenseitig verwalteten Schlüsseln werden die Daten, die Sie in Ihrem Azure Cosmos DB-Konto speichern, zweimal verschlüsselt:

Einmal durch die Standardverschlüsselung, die mit Microsoft-verwalteten Schlüsseln ausgeführt wurde.
Einmal durch die zusätzliche Verschlüsselung mit den kundenseitig verwalteten Schlüsseln.

Die Mehrfachverschlüsselung gilt nur für den Azure Cosmos DB-Transaktionshauptspeicher. Einige Features umfassen die interne Replikation Ihrer Daten auf eine zweite Speicherebene, bei der keine Mehrfachverschlüsselung bereitgestellt wird, auch wenn kundenseitig verwaltete Schlüssel verwendet werden. Zu diesen Features zählen:

Schlüsselrotation

Die Rotation des kundenseitig verwalteten Schlüssels, der von Ihrem Azure Cosmos DB-Konto verwendet wird, kann auf zwei Arten erfolgen.

Erstellen Sie eine neue Version des Schlüssels, der derzeit von Azure Key Vault verwendet wird:

Tauschen Sie den derzeit verwendeten Schlüssel gegen einen anderen aus, indem Sie den Schlüssel-URI in Ihrem Konto aktualisieren. Navigieren Sie im Azure-Portal zu Ihrem Azure Cosmos DB-Konto, und wählen Sie im linken Menü die Option Datenverschlüsselung aus:

Screenshot: Option „Datenverschlüsselung“ im Navigationsmenü der Ressource

Ersetzen Sie dann den Schlüssel-URI durch den neuen Schlüssel, den Sie verwenden möchten, und wählen Sie Speichern aus:

Gehen Sie folgendermaßen vor, um das gleiche Ergebnis in PowerShell zu erzielen:

# Variable for resource group name
$RESOURCE_GROUP_NAME = "<resource-group-name>"

# Variable for account name
$ACCOUNT_NAME = "<globally-unique-account-name>"

# Variable for new key URI in the key vault
$NEW_KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<new-key-name>"

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME 
    Name = $ACCOUNT_NAME
    ResourceType = "Microsoft.DocumentDb/databaseAccounts"
}
$ACCOUNT = Get-AzResource @parameters

$ACCOUNT.Properties.keyVaultKeyUri = $NEW_KEY_VAULT_KEY_URI

$ACCOUNT | Set-AzResource -Force

Der vorherige Schlüssel oder die vorherige Schlüsselversion kann deaktiviert werden, wenn in den Azure Key Vault-Überwachungsprotokollen keine Aktivitäten mehr von Azure Cosmos DB für diesen Schlüssel oder diese Schlüsselversion angezeigt werden. Nach einer 24-stündigen Schlüsselrotation sollten keine Aktivitäten mehr mit dem vorherigen Schlüssel oder der vorherigen Schlüsselversion erfolgen.

Die automatische Schlüsselrotation in Azure Key Vault wird unterstützt, solange der vorherige Schlüssel nicht deaktiviert oder gelöscht wird. Die internen Systeme benötigen einige Zeit, um die neue Version des Schlüssels zu verarbeiten, nachdem sie überprüft haben, dass das Konto nicht gesperrt ist oder sich in der Übergangsphase zur Aktivierung von kundenverwalteten Schlüsseln befindet.

Fehlerbehandlung

Wenn bei der Verwendung von kundenseitig verwalteten Schlüsseln in Azure Cosmos DB Fehler auftreten, gibt Azure Cosmos DB die Fehlerdetails zusammen mit einem HTTP-Unterstatuscode in der Antwort zurück. Mit diesem HTTP-Unterstatuscode können Sie die Grundursache des Problems debuggen. Eine Liste der unterstützten HTTP-Unterstatuscodes finden Sie im Artikel HTTP-Statuscodes für Azure Cosmos DB.

Häufig gestellte Fragen

Hier finden Sie häufig gestellte Fragen zum Einrichten von kundenseitig verwalteten Schlüsseln in Azure Cosmos DB.

Fallen weitere Gebühren für die Aktivierung von kundenseitig verwalteten Schlüsseln an?

Nein, es fallen keine Kosten für die Aktivierung dieses Features an.

Wie wirken sich kundenseitig verwaltete Schlüssel auf die Kapazitätsplanung aus?

Wenn Sie kundenseitig verwaltete Schlüssel verwenden, erhöht sich die Anzahl der von Ihren Datenbankvorgängen genutzten Anforderungseinheiten entsprechend der zusätzlichen Verarbeitungsschritte, die zum Durchführen der Ver- und Entschlüsselung Ihrer Daten erforderlich sind. Dieser zusätzliche RU-Verbrauch kann zu einer geringfügig höheren Auslastung Ihrer bereitgestellten Kapazität führen. Die folgende Tabelle dient als Orientierungshilfe:

Vorgangsart	Erhöhung der Anforderungseinheiten
Punktlesevorgänge (Abrufen von Elementen nach ID)	5 % pro Vorgang
Beliebiger Schreibvorgang	6 % pro Vorgang \| etwa 0,06 RU pro indizierte Eigenschaft
Abfragen, Lesen des Änderungsfeeds oder Konfliktfeeds	15 % pro Vorgang

Welche Daten werden mit den vom Kunden verwalteten Schlüsseln verschlüsselt?

Mit Ausnahme der nachfolgend aufgeführten Metadaten werden alle in Ihrem Azure Cosmos DB-Konto gespeicherten Daten mit den vom Kunden verwalteten Schlüsseln verschlüsselt:

Die Namen Ihrer Azure Cosmos DB-Konten, -Datenbanken und -Container
Die Namen Ihrer gespeicherten Prozeduren
Die in Ihren Indizierungsrichtlinien deklarierten Eigenschaftenpfade
Die Werte der Partitionsschlüssel Ihrer Container

Werden vom Kunden verwaltete Schlüssel für vorhandene Azure Cosmos DB-Konten unterstützt?

Ja. Weitere Informationen finden Sie unter Einrichten von kundenseitig verwalteten Schlüsseln für Ihr vorhandenes Azure Cosmos DB-Konto.

Können kundenseitig verwaltete Schlüssel mit dem Azure Cosmos DB-Analysespeicher verwendet werden?

Ja, Azure Synapse Link unterstützt nur das Konfigurieren von kundenseitig verwalteten Schlüsseln mithilfe der verwalteten Identität Ihres Azure Cosmos DB-Kontos. Sie müssen die verwaltete Identität Ihres Azure Cosmos DB-Kontos in Ihrer Azure Key Vault-Zugriffsrichtlinie verwenden, bevor Sie Azure Synapse Link für Ihr Konto aktivieren. Eine Schrittanleitung zum Aktivieren von verwalteten Identitäten und ihrer Verwendung in einer Zugriffsrichtlinie finden Sie unter Zugreifen auf Azure Key Vault aus Azure Cosmos DB mithilfe einer verwalteten Identität.

Ist die Unterstützung einer feineren Granularität als bei Schlüsseln auf Kontoebene geplant?

Derzeit nicht. Es werden jedoch Schlüssel auf Containerebene in Erwägung gezogen.

Woran erkenne ich, dass kundenseitig verwaltete Schlüssel für mein Azure Cosmos DB-Konto aktiviert sind?

Navigieren Sie im Azure-Portal zu Ihrem Azure Cosmos DB-Konto, und suchen Sie im linken Menü nach dem Eintrag Datenverschlüsselung. Wenn dieser Eintrag vorhanden ist, sind kundenseitig verwaltete Schlüssel für Ihr Konto aktiviert:

Screenshot: Option „Datenverschlüsselung“ im Navigationsmenü der Ressource

Sie können die Details Ihres Azure Cosmos DB-Kontos auch programmgesteuert abrufen und überprüfen, ob die Eigenschaft keyVaultKeyUri vorhanden ist.

Wie wirken sich die vom Kunden verwalteten Schlüssel auf regelmäßige Backups aus?

Azure Cosmos DB erstellt regelmäßige und automatische Sicherungen der in Ihrem Konto gespeicherten Daten. Bei diesem Vorgang werden die verschlüsselten Daten gesichert.

Die folgenden Bedingungen sind für die erfolgreiche Wiederherstellung eines periodischen Backups erforderlich:

Der Verschlüsselungsschlüssel, den Sie zum Zeitpunkt des Backups verwendet haben, ist erforderlich und muss in Azure Key Vault verfügbar sein. Diese Bedingung erfordert, dass kein Widerruf erfolgt ist und die Version des Schlüssels, die zum Zeitpunkt der Sicherung verwendet wurde, noch aktiviert ist.
Wenn Sie eine systemseitig zugewiesene verwaltete Identität in der Zugriffsrichtlinie verwendet haben, müssen Sie vor der Wiederherstellung Ihrer Daten vorübergehend Zugriff auf die Azure Cosmos DB-Erstanbieteridentität gewähren. Dies ist erforderlich, da eine systemseitig zugewiesene verwaltete Identität spezifisch für ein Konto ist und im Zielkonto nicht wiederverwendet werden kann. Sobald die Daten im Zielkonto vollständig wiederhergestellt sind, können Sie die gewünschte Identitätskonfiguration festlegen und die Erstanbieteridentität aus der Key Vault-Zugriffsrichtlinie entfernen.

Wie wirken sich kundenseitig verwaltete Schlüssel auf die fortlaufende Sicherung aus?

Azure Cosmos DB bietet Ihnen die Möglichkeit, fortlaufende Sicherungen für Ihr Konto zu konfigurieren. Mit der fortlaufenden Sicherung können Sie den Stand Ihrer Daten zu einem beliebigen Zeitpunkt innerhalb der letzten 30 Tage wiederherstellen. Um fortlaufende Sicherungen für ein Konto zu verwenden, für das kundenseitig verwaltete Schlüssel aktiviert sind, müssen Sie eine systemseitig oder benutzerseitig zugewiesene verwaltete Identität in der Key Vault-Zugriffsrichtlinie verwenden. Die Azure Cosmos DB-Erstanbieteridentität wird derzeit nicht für Konten unterstützt, die fortlaufende Sicherungen verwenden.

Voraussetzungen für kundenseitig verwaltete Schlüssel aktivierte Konten zum Aktualisieren der vom Benutzer zugewiesenen Identität.

Fügen Sie dem Cosmos DB-Konto eine benutzerseitig zugewiesene Identität hinzu, und erteilen Sie Berechtigungen in der Zugriffsrichtlinie für den Schlüsseltresor.
Legen Sie die vom Benutzer zugewiesene Identität über die Azure CLI oder ARM als Standardidentität fest.

az cosmosdb update --resource-group MyResourceGroup --name MyAccountName --default-identity UserAssignedIdentity=/subscriptions/MySubscriptionId/resourcegroups/MyResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MyUserAssignedIdentity

Für eine erfolgreiche Zeitpunktwiederherstellung müssen die folgenden Bedingungen erfüllt sein:

Der Verschlüsselungsschlüssel, den Sie zum Zeitpunkt des Backups verwendet haben, ist erforderlich und muss in Azure Key Vault verfügbar sein. Dies bedeutet, dass kein Widerruf erfolgt ist und die Version des Schlüssels, die zum Zeitpunkt der Sicherung verwendet wurde, noch aktiviert ist.
Sie müssen sicherstellen, dass die benutzerseitig zugewiesene verwaltete Identität, die ursprünglich für das Quellkonto verwendet wurde, weiterhin in der Key Vault-Zugriffsrichtlinie angegeben ist.

Wichtig

Wenn Sie den Verschlüsselungsschlüssel widerrufen, bevor Sie Ihr Konto löschen, fehlen in der Sicherung Ihres Kontos möglicherweise die Daten, die bis zu 1 Stunde vor dem Widerruf geschrieben wurden.

Wie sperre/widerrufe ich einen Verschlüsselungsschlüssel?

Die Schlüsselsperrung erfolgt durch Deaktivieren der aktuellen Version des Schlüssels:

Alternativ können Sie zum Sperren aller Schlüssel in einer Azure Key Vault-Instanz die dem Azure Cosmos DB-Prinzipal erteilte Zugriffsrichtlinie löschen:

Welche Vorgänge sind nach dem Sperren/Widerrufen eines vom Kunden verwalteten Schlüssels verfügbar?

Das Löschen von Konten ist der einzige mögliche Vorgang, wenn der Verschlüsselungsschlüssel widerrufen wurde.

Weisen Sie dem wiederhergestellten Datenbankkonto eine neue verwaltete Identität zu, um weiterhin auf das Datenbankkonto zuzugreifen oder den Zugriff wiederherzustellen.

Benutzerseitig zugewiesene Identität ist an ein angegebenes Cosmos DB-Konto gebunden. Wenn wir einem Konto eine benutzerseitig zugewiesene Identität zuweisen, leitet ARM die Anforderung an verwaltete Dienstidentitäten weiter, um diese Verbindung herzustellen. Derzeit übertragen wir Benutzeridentitätsinformationen während der Wiederherstellung (sowohl bei der fortlaufenden als auch der regelmäßigen Wiederherstellung) von CMK + benutzerseitig zugewiesene Identität vom Quelldatenbankkonto an das Zieldatenbankkonto.

Da die Identitätsmetadaten an das Quelldatenbankkonto gebunden sind, und der Wiederherstellungsworkflow die Identität nicht erneut auf das Zieldatenbankkonto bezieht, führt dies dazu, dass sich die wiederhergestellten Datenbankkonten in einem ungültigen Zustand befinden und nicht mehr auf das Quellkonto zugegriffen werden kann, nachdem das Quellkonto gelöscht wurde und die Verlängerungszeit der Identität abgelaufen ist.

Schritte zum Zuweisen einer neuen verwalteten Identität:

Nächste Schritte

Erfahren Sie mehr über die Datenverschlüsselung in Azure Cosmos DB.

Freigeben über

Konfigurieren von kundenseitig verwalteten Schlüsseln für Ihr Azure Cosmos DB-Konto mit Azure Key Vault

Voraussetzungen

Registrieren des Azure Cosmos DB-Ressourcenanbieters

Konfigurieren Ihrer Azure Key Vault-Instanz

Auswählen des bevorzugten Sicherheitsmodells

Hinzufügen einer Zugriffsrichtlinie

Hinzufügen von Rollen für die rollenbasierte Zugriffssteuerung

Überprüfen, ob die Rollen richtig festgelegt wurden

Generieren eines Schlüssels in Azure Key Vault

Erstellen eines neuen Azure Cosmos DB-Kontos

Verwenden einer verwalteten Identität in der Azure Key Vault-Zugriffsrichtlinie

Verwenden von kundenseitig verwalteten Schlüsseln mit fortlaufender Sicherung

Wiederherstellen eines fortlaufenden Kontos, das mit verwalteter Identität konfiguriert ist

Kundenseitig verwaltete Schlüssel und Mehrfachverschlüsselung

Schlüsselrotation

Fehlerbehandlung

Häufig gestellte Fragen

Fallen weitere Gebühren für die Aktivierung von kundenseitig verwalteten Schlüsseln an?

Wie wirken sich kundenseitig verwaltete Schlüssel auf die Kapazitätsplanung aus?

Welche Daten werden mit den vom Kunden verwalteten Schlüsseln verschlüsselt?

Werden vom Kunden verwaltete Schlüssel für vorhandene Azure Cosmos DB-Konten unterstützt?

Können kundenseitig verwaltete Schlüssel mit dem Azure Cosmos DB-Analysespeicher verwendet werden?

Ist die Unterstützung einer feineren Granularität als bei Schlüsseln auf Kontoebene geplant?

Woran erkenne ich, dass kundenseitig verwaltete Schlüssel für mein Azure Cosmos DB-Konto aktiviert sind?

Wie wirken sich die vom Kunden verwalteten Schlüssel auf regelmäßige Backups aus?

Wie wirken sich kundenseitig verwaltete Schlüssel auf die fortlaufende Sicherung aus?

Wie sperre/widerrufe ich einen Verschlüsselungsschlüssel?

Welche Vorgänge sind nach dem Sperren/Widerrufen eines vom Kunden verwalteten Schlüssels verfügbar?

Weisen Sie dem wiederhergestellten Datenbankkonto eine neue verwaltete Identität zu, um weiterhin auf das Datenbankkonto zuzugreifen oder den Zugriff wiederherzustellen.

Nächste Schritte

Feedback

Zusätzliche Ressourcen