Configurare le chiavi gestite dal cliente per l'account Azure Cosmos DB con Azure Key Vault

SI APPLICA A: Nosql Mongodb Cassandra Gremlin Tabella

I dati archiviati nell'account Azure Cosmos DB vengono crittografati automaticamente e facilmente crittografati con chiavi gestite da Microsoft (chiavi gestite dal servizio). Facoltativamente, è possibile scegliere di aggiungere un secondo livello di crittografia con chiavi gestite dal cliente o CMK.

Livelli di crittografia relativi ai dati dei clienti

È necessario archiviare le chiavi gestite dal cliente in Azure Key Vault e specificare una chiave per ogni account Azure Cosmos DB abilitato con chiavi gestite dal cliente. Questa chiave viene usata per crittografare tutti i dati archiviati nell'account.

Nota

Attualmente, le chiavi gestite dal cliente sono disponibili solo per i nuovi account Azure Cosmos DB. È necessario configurarle durante la creazione dell'account.

Registrare il provider di risorse Azure Cosmos DB per la sottoscrizione di Azure

  1. Accedere al portale di Azure, passare alla sottoscrizione di Azure e selezionare Provider di risorse nella scheda Impostazioni:

    Voce provider di risorse dal menu a sinistra

  2. Cercare il provider di risorse Microsoft.DocumentDB. Verificare che il provider di risorse sia già contrassegnato come registrato. In caso contrario, scegliere il provider di risorse e selezionare Registra:

    Registrazione del provider di risorse Microsoft.DocumentDB

Configurare l'istanza di Azure Key Vault

Importante

L'istanza di Azure Key Vault deve essere accessibile tramite l'accesso alla rete pubblica o consentire ai servizi di Microsoft attendibili di ignorare il firewall. Non è possibile usare un'istanza accessibile esclusivamente tramite endpoint privati per ospitare le chiavi gestite dal cliente.

Per usare le chiavi gestite dal cliente con Azure Cosmos DB è necessario impostare due proprietà nell'istanza di Azure Key Vault che si intende usare per ospitare le chiavi di crittografia: Eliminazione temporanea e Protezione dall'eliminazione.

Se si crea una nuova istanza di Azure Key Vault, abilitare queste proprietà durante la creazione:

Abilitazione delle proprietà Eliminazione temporanea e Protezione dall'eliminazione per una nuova istanza di Azure Key Vault

Se si usa un'istanza di Azure Key Vault esistente, è possibile verificare che queste proprietà siano abilitate nella sezione Proprietà del portale di Azure. Se una di queste proprietà non è abilitata, vedere le sezioni "Abilitazione della funzione di eliminazione temporanea" e "Abilitazione del flag di protezione dall'eliminazione" in uno degli articoli seguenti:

Aggiungere un criterio di accesso all'istanza di Azure Key Vault

  1. Dal portale di Azure passare all'istanza di Azure Key Vault che si intende usare per ospitare le chiavi di crittografia. Selezionare Criteri di accesso nel menu a sinistra:

    Criteri di accesso dal menu a sinistra

  2. Selezionare + Aggiungi criterio di accesso.

  3. Nel menu a discesa Autorizzazioni chiave selezionare le autorizzazioni Recupera, Annulla il wrapping della chiave e Esegui il wrapping della chiave:

    Selezione delle autorizzazioni corrette

  4. In Selezionare un'entità selezionare Nessuna selezione.

  5. Cercare l'entità azure Cosmos DB e selezionarla (per semplificare la ricerca, è anche possibile cercare in base all'ID applicazione: a232010e-820c-4083-83bb-3ace5fc29d0b per qualsiasi area di Azure, ad eccezione di Azure per enti pubblici aree in cui l'ID applicazione è 57506a73-e302-42a9-b869-6f12d9ec29e9). Se l'entità di sicurezza Azure Cosmos DB non è presente nell'elenco, potrebbe essere necessario registrare nuovamente il provider di risorse Microsoft.DocumentDB come descritto nella sezione Registrare il provider di risorse di questo articolo.

    Nota

    In questo modo viene registrata l'identità di prima parte di Azure Cosmos DB nei criteri di accesso di Azure Key Vault. Per sostituire questa identità di prima parte dall'identità gestita dell'account Azure Cosmos DB, vedere Uso di un'identità gestita nei criteri di accesso di Azure Key Vault.

  6. Scegliere Seleziona nella parte inferiore.

    Selezionare l'entità di sicurezza Azure Cosmos DB

  7. Selezionare Aggiungi per aggiungere il nuovo criterio di accesso.

  8. Selezionare Salva nell'istanza di Key Vault per salvare tutte le modifiche.

Generare una chiave in Azure Key Vault

  1. Dal portale di Azure passare all'istanza di Azure Key Vault che si intende usare per ospitare le chiavi di crittografia. Scegliere quindi Chiavi nel menu a sinistra:

    Voce chiavi dal menu a sinistra

  2. Selezionare Genera/Importa, specificare un nome per la nuova chiave e selezionare le dimensioni della chiave RSA. Si consiglia di usare minimo 3072 per motivi di sicurezza. quindi selezionare Crea:

    Creare una nuova chiave

  3. Dopo aver creato la chiave, selezionare la chiave appena creata e quindi la relativa versione corrente.

  4. Copiare l'Identificatore chiave della chiave, ad eccezione della parte dopo l'ultima barra:

    Copia dell'identificatore chiave della chiave

Creare un nuovo account Azure Cosmos DB

Uso del portale di Azure

Quando si crea un nuovo account Azure Cosmos DB dal portale di Azure, scegliere Chiave gestita dal cliente nel passaggio Crittografia. Nel campo URI della chiave incollare l'URI/identificatore chiave della chiave di Azure Key Vault copiata nel passaggio precedente:

Impostazione dei parametri della chiave gestita dal cliente nel portale di Azure

Uso di Azure PowerShell

Quando si crea un nuovo account Azure Cosmos DB con PowerShell:

  • Passare l'URI della chiave di Azure Key Vault copiata in precedenza nella proprietà keyVaultKeyUri in PropertyObject.

  • Usare 2019-12-12 o versioni successive come versione dell'API.

Importante

Per creare correttamente l'account con chiavi gestite dal cliente, è necessario impostare in modo esplicito la proprietà locations.

$resourceGroupName = "myResourceGroup"
$accountLocation = "West US 2"
$accountName = "mycosmosaccount"

$failoverLocations = @(
    @{ "locationName"="West US 2"; "failoverPriority"=0 }
)

$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$failoverLocations;
    "keyVaultKeyUri" = "https://<my-vault>.vault.azure.net/keys/<my-key>";
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2019-12-12" -ResourceGroupName $resourceGroupName `
    -Location $accountLocation -Name $accountName -PropertyObject $CosmosDBProperties

Dopo aver creato l'account, è possibile verificare che le chiavi gestite dal cliente siano state abilitate recuperando l'URI della chiave di Azure Key Vault:

Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    | Select-Object -ExpandProperty Properties `
    | Select-Object -ExpandProperty keyVaultKeyUri

Uso di un modello di Azure Resource Manager

Quando si crea un nuovo account Azure Cosmos DB tramite un modello di azure Resource Manager:

  • Passare l'URI della chiave di Azure Key Vault copiata in precedenza nella proprietà keyVaultKeyUri nell'oggetto properties.

  • Usare 2019-12-12 o versioni successive come versione dell'API.

Importante

Per creare correttamente l'account con chiavi gestite dal cliente, è necessario impostare in modo esplicito la proprietà locations.

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

Distribuire il modello con lo script di PowerShell seguente:

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$accountLocation = "West US 2"
$keyVaultKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-key>"

New-AzResourceGroupDeployment `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile "deploy.json" `
    -accountName $accountName `
    -location $accountLocation `
    -keyVaultKeyUri $keyVaultKeyUri

Con l'interfaccia della riga di comando di Azure

Quando si crea un nuovo account Azure Cosmos DB tramite l'interfaccia della riga di comando di Azure, passare l'URI della chiave di Azure Key Vault copiata in precedenza nel --key-uri parametro.

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='West US 2' failoverPriority=0 isZoneRedundant=False \
    --key-uri $keyVaultKeyUri

Dopo aver creato l'account, è possibile verificare che le chiavi gestite dal cliente siano state abilitate recuperando l'URI della chiave di Azure Key Vault:

az cosmosdb show \
    -n $accountName \
    -g $resourceGroupName \
    --query keyVaultKeyUri

Uso di un'identità gestita nei criteri di accesso di Azure Key Vault

Questo criterio di accesso garantisce che le chiavi di crittografia possano essere accessibili dall'account Azure Cosmos DB. I criteri di accesso vengono implementati concedendole l'accesso a un'identità di Azure Active Directory (AD) specifica. Sono supportati due tipi di identità:

  • L'identità di prima parte di Azure Cosmos DB può essere usata per concedere l'accesso al servizio Azure Cosmos DB.
  • L'identità gestita dell'account Azure Cosmos DB può essere usata per concedere l'accesso all'account in modo specifico.

Per usare un'identità gestita assegnata dal sistema

Poiché un'identità gestita assegnata dal sistema può essere recuperata solo dopo la creazione dell'account, è comunque necessario creare inizialmente l'account usando l'identità di prima parte, come descritto in precedenza. Quindi:

  1. Se l'identità gestita assegnata dal sistema non è stata configurata durante la creazione dell'account, abilitare un'identità gestita assegnata dal sistema nell'account e copiare l'identità assegnata dall'account principalId .

  2. Aggiungere un nuovo criterio di accesso all'account azure Key Vault come descritto in precedenza, ma usando l'oggetto copiato nel passaggio precedente anziché l'identità principalId di prima parte di Azure Cosmos DB.

  3. Aggiornare l'account Azure Cosmos DB per specificare che si vuole usare l'identità gestita assegnata dal sistema quando si accedono alle chiavi di crittografia in Azure Key Vault. Sono disponibili due opzioni:

    • Specificare la proprietà nel modello di Azure Resource Manager dell'account:

      {
          "type": " Microsoft.DocumentDB/databaseAccounts",
          "properties": {
              "defaultIdentity": "SystemAssignedIdentity",
              // ...
          },
          // ...
      }
      
    • Aggiornare l'account con l'interfaccia della riga di comando di Azure:

          resourceGroupName='myResourceGroup'
          accountName='mycosmosaccount'
      
          az cosmosdb update --resource-group $resourceGroupName --name $accountName --default-identity "SystemAssignedIdentity"
      
  4. Facoltativamente, è possibile rimuovere l'identità di prima parte di Azure Cosmos DB dai criteri di accesso di Azure Key Vault.

Per usare un'identità gestita assegnata dall'utente

  1. Quando si creano i nuovi criteri di accesso nell'account di Azure Key Vault come descritto in precedenza, usare l'identità Object ID gestita che si vuole usare anziché l'identità di prima parte di Azure Cosmos DB.

  2. Quando si crea l'account Azure Cosmos DB, è necessario abilitare l'identità gestita assegnata dall'utente e specificare che si vuole usare questa identità quando si accede alle chiavi di crittografia in Azure Key Vault. Le opzioni includono:

    • Uso di un modello di Azure Resource Manager:

      {
          "type": "Microsoft.DocumentDB/databaseAccounts",
          "identity": {
              "type": "UserAssigned",
              "userAssignedIdentities": {
                  "<identity-resource-id>": {}
              }
          },
          // ...
          "properties": {
              "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>",
              "keyVaultKeyUri": "<key-vault-key-uri>"
              // ...
          }
      }
      
    • Uso dell'interfaccia della riga di comando di Azure:

      resourceGroupName='myResourceGroup'
      accountName='mycosmosaccount'
      keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'
      
      az cosmosdb create \
          -n $accountName \
          -g $resourceGroupName \
          --key-uri $keyVaultKeyUri
          --assign-identity <identity-resource-id>
          --default-identity "UserAssignedIdentity=<identity-resource-id>"  
      

Usare CMK con backup continuo

È possibile creare un account di backup continuo usando l'interfaccia della riga di comando di Azure o un modello di Resource Manager di Azure.

Attualmente è supportata solo l'identità gestita assegnata dall'utente per la creazione di account di backup continui.

Per creare un account di backup continuo usando l'interfaccia della riga di comando di Azure

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --key-uri $keyVaultKeyUri \
    --locations regionName=<Location> \
    --assign-identity <identity-resource-id> \
    --default-identity "UserAssignedIdentity=<identity-resource-id>" \
    --backup-policy-type Continuous 

Per creare un account di backup continuo usando un modello di Resource Manager di Azure

Quando si crea un nuovo account Azure Cosmos DB tramite un modello di azure Resource Manager:

  • Passare l'URI della chiave di Azure Key Vault copiata in precedenza nella proprietà keyVaultKeyUri nell'oggetto properties.
  • Usare 2021-11-15 o versione successiva come versione dell'API.

Importante

È necessario impostare in modo esplicito la locations proprietà per la creazione dell'account con chiavi gestite dal cliente, come illustrato nell'esempio precedente.

 {
    "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>"
        // ...
    }
}

Chiavi gestite dal cliente e doppia crittografia

I dati archiviati nell'account Azure Cosmos DB quando si usano chiavi gestite dal cliente vengono crittografati due volte:

  • Una volta eseguita la crittografia predefinita con chiavi gestite da Microsoft.
  • Una volta eseguita la crittografia aggiuntiva con chiavi gestite dal cliente.

La crittografia doppia si applica solo all'archiviazione transazionale principale di Azure Cosmos DB. Alcune funzionalità comportano la replica interna dei dati in un secondo livello di archiviazione in cui la doppia crittografia non viene fornita, anche con chiavi gestite dal cliente. Queste funzionalità includono:

Rotazione delle chiavi

La rotazione della chiave gestita dal cliente usata dall'account Azure Cosmos DB può essere eseguita in due modi.

  • Creare una nuova versione della chiave attualmente usata da Azure Key Vault:

    Screenshot dell'opzione Nuova versione nella pagina Versioni del portale di Azure.

  • Scambiare la chiave attualmente usata con una diversa aggiornando l'URI della chiave nell'account. Dal portale di Azure passare all'account Azure Cosmos DB e selezionare Crittografia dati dal menu a sinistra:

    Screenshot dell'opzione di menu Crittografia dati nella portale di Azure.

    Sostituire quindi l'URI chiave con la nuova chiave da usare e selezionare Salva:

    Screenshot dell'opzione Salva nella pagina Chiave della portale di Azure.

    Ecco come ottenere lo stesso risultato in PowerShell:

    $resourceGroupName = "myResourceGroup"
    $accountName = "mycosmosaccount"
    $newKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-new-key>"
    
    $account = Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
        -ResourceType "Microsoft.DocumentDb/databaseAccounts"
    
    $account.Properties.keyVaultKeyUri = $newKeyUri
    
    $account | Set-AzResource -Force
    

La chiave o la versione chiave precedente possono essere disabilitate dopo che i log di controllo di Azure Key Vault non mostrano più attività da Azure Cosmos DB in tale chiave o versione della chiave. Nessuna attività deve essere eseguita sulla versione precedente della chiave o della chiave dopo 24 ore di rotazione delle chiavi.

Gestione degli errori

Se si verificano errori con chiavi gestite dal cliente in Azure Cosmos DB, Azure Cosmos DB restituisce i dettagli dell'errore insieme a un codice substatus HTTP nella risposta. È possibile usare il codice substatus HTTP per eseguire il debug della causa radice del problema. Per ottenere l'elenco dei codici secondari HTTP supportati, vedere l'articolo Codici di stato HTTP per Azure Cosmos DB .

Domande frequenti

Ci sono altri addebiti per abilitare le chiavi gestite dal cliente?

No, non è previsto alcun addebito per abilitare questa funzionalità.

In che modo le chiavi gestite dal cliente influiscono sulla pianificazione della capacità?

Le unità richiesta usate dalle operazioni del database vedono un aumento per riflettere l'elaborazione aggiuntiva necessaria per eseguire la crittografia e la decrittografia dei dati quando si usano chiavi gestite dal cliente. Il consumo di UR aggiuntivo può causare un utilizzo leggermente superiore della capacità di cui è stato effettuato il provisioning. Usare la tabella seguente come guida:

Tipo di operazione Aumento delle unità richiesta
Letture punto (recupero di elementi in base al relativo ID) + 5% per operazione
Qualsiasi operazione di scrittura + 6% per operazione
Circa + 0,06 UR per ogni proprietà indicizzata
Query, lettura del feed di modifiche o feed di conflitti + 15% per operazione

Quali dati vengono crittografati con le chiavi gestite dal cliente?

Tutti i dati archiviati nell'account Azure Cosmos DB vengono crittografati con le chiavi gestite dal cliente, ad eccezione dei metadati seguenti:

Le chiavi gestite dal cliente sono supportate per gli account Azure Cosmos DB esistenti?

Questa funzionalità è attualmente disponibile solo per i nuovi account.

È possibile usare chiavi gestite dal cliente con l'archivio analitico di Azure Cosmos DB?

Sì, Azure Synapse Link supporta solo la configurazione delle chiavi gestite dal cliente usando l'identità gestita dell'account Azure Cosmos DB. È necessario usare l'identità gestita dell'account Azure Cosmos DB nel criterio di accesso di Azure Key Vault prima di abilitare Azure Synapse Collegamento all'account. Per una guida su come abilitare l'identità gestita e usarla in un criterio di accesso, vedere Accedere ad Azure Key Vault da Azure Cosmos DB usando un'identità gestita.

È previsto un piano per supportare una maggiore granularità rispetto alle chiavi a livello di account?

Non attualmente, ma vengono prese in considerazione le chiavi a livello di contenitore.

Come è possibile stabilire se le chiavi gestite dal cliente sono abilitate nell'account Azure Cosmos DB?

Dal portale di Azure passare all'account Azure Cosmos DB e controllare la voce Crittografia dati nel menu a sinistra; se questa voce esiste, le chiavi gestite dal cliente sono abilitate nell'account:

Voce di menu Crittografia dati

È anche possibile recuperare i dettagli dell'account keyVaultKeyUri Azure Cosmos DB a livello di codice e cercare la presenza della proprietà. Vedere sopra per informazioni su come eseguire questa operazione in PowerShell e usando l'interfaccia della riga di comando di Azure.

In che modo le chiavi gestite dal cliente influiscono sui backup periodici?

Azure Cosmos DB esegue backup regolari e automatici dei dati archiviati nell'account. Questa operazione esegue il backup dei dati crittografati.

Le condizioni seguenti sono necessarie per ripristinare correttamente un backup periodico:

  • La chiave di crittografia usata al momento del backup è necessaria e deve essere disponibile in Azure Key Vault. Questa condizione richiede che non sia stata eseguita alcuna revoca e che la versione della chiave usata al momento del backup sia ancora abilitata.
  • Se è stata usata un'identità gestita assegnata dal sistema nei criteri di accesso, concedere temporaneamente l'accesso all'identità di prima parte di Azure Cosmos DB prima di ripristinare i dati. Questo requisito esiste perché un'identità gestita assegnata dal sistema è specifica di un account e non può essere riutilizzata nell'account di destinazione. Dopo aver ripristinato completamente i dati nell'account di destinazione, è possibile impostare la configurazione dell'identità desiderata e rimuovere l'identità di prima parte dal criterio di accesso Key Vault.

In che modo le chiavi gestite dal cliente influiscono sui backup continui?

Azure Cosmos DB offre l'opzione per configurare i backup continui nell'account. Con i backup continui, è possibile ripristinare i dati in qualsiasi momento entro i 30 giorni precedenti. Per usare i backup continui in un account in cui sono abilitate le chiavi gestite dal cliente, è necessario usare un'identità gestita assegnata dall'utente nei criteri di accesso Key Vault. Le identità di prima parte o le identità gestite assegnate dal sistema di Azure Cosmos DB non sono attualmente supportate negli account usando backup continui.

Le condizioni seguenti sono necessarie per eseguire correttamente un ripristino temporizzato:

  • La chiave di crittografia usata al momento del backup è necessaria e deve essere disponibile in Azure Key Vault. Questo requisito indica che non è stata effettuata alcuna revoca e la versione della chiave usata al momento del backup è ancora abilitata.
  • È necessario assicurarsi che l'identità gestita assegnata dall'utente utilizzata originariamente nell'account di origine sia ancora dichiarata nei criteri di accesso Key Vault.

Importante

Se si revoca la chiave di crittografia prima di eliminare l'account, il backup dell'account potrebbe perdere i dati scritti fino a 1 ora prima dell'esecuzione della revoca.

Come si revoca una chiave di crittografia?

La revoca della chiave viene eseguita disabilitando la versione più recente della chiave:

Disabilitare la versione di una chiave

In alternativa, per revocare tutte le chiavi da un'istanza di Azure Key Vault, è possibile eliminare i criteri di accesso concessi all'entità di sicurezza di Azure Cosmos DB:

Eliminazione dei criteri di accesso per l'entità di sicurezza di Azure Cosmos DB

Quali operazioni sono disponibili dopo la revoca di una chiave gestita dal cliente?

L'unica operazione possibile quando la chiave di crittografia è stata revocata è l'eliminazione dell'account.

Passaggi successivi