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 con le chiavi gestite da Microsoft (chiavi gestite dal servizio). Facoltativamente, è possibile scegliere di aggiungere un secondo livello di crittografia con chiavi gestite dal cliente.

È necessario archiviare le chiavi gestite dal cliente in Azure Key Vault e fornire 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

Per abilitare le chiavi gestite dal cliente negli account Azure Cosmos DB esistenti, è possibile fare riferimento al collegamento qui per altri dettagli

Avviso

Nelle tabelle dell'API Cassandra i nomi dei campi seguenti sono riservati usando chiavi gestite dal cliente negli account:

• id
• ttl
• _ts
• _etag
• _rid
• _self
• _attachments
• _epk

Quando le chiavi gestite dal cliente non sono abilitate, vengono riservati solo i nomi dei campi che iniziano con __sys_.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.

Registrare il provider di risorse Azure Cosmos DB

Se il provider di risorse Microsoft.DocumentDB non è già registrato, come primo passaggio è necessario registrare questo provider.

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

   

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:

   

Configurare l'istanza di Azure Key Vault

Importante

L'istanza di Azure Key Vault deve essere accessibile tramite l'accesso alla rete pubblica o deve consentire ai servizi Microsoft attendibili di ignorare il firewall. Un'istanza accessibile esclusivamente tramite endpoint privati non può essere usata 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 dalla rimozione definitiva.

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

   

2. 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:

   • Come usare la funzionalità di eliminazione temporanea con PowerShell
   • Come usare la funzionalità di eliminazione temporanea con l'interfaccia della riga di comando di Azure

Scelta del modello di sicurezza preferito

Dopo aver abilitato la protezione dalla rimozione definitiva e l'eliminazione temporanea, nella scheda criteri di accesso è possibile scegliere il modello di autorizzazione preferito da usare. I criteri di accesso vengono settati per impostazione predefinita, ma è supportato anche il controllo degli accessi in base al ruolo di Azure.

Le autorizzazioni necessarie devono essere concesse per permettere a Cosmos DB di usare la chiave di crittografia. Questo passaggio varia a seconda che Azure Key Vault usi criteri di accesso o il controllo degli accessi in base al ruolo.

Nota

È importante notare che può essere attivo un solo modello di sicurezza alla volta, quindi non è necessario eseguire il seeding del controllo degli accessi in base al ruolo se Azure Key Vault è impostato per l’utilizzo dei criteri di accesso e viceversa.

Aggiungere un criterio di accesso

In questa variante usare l'entità di sicurezza di Azure Cosmos DB per creare criteri di accesso con le autorizzazioni appropriate.

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:

   

2. Selezionare + Aggiungi un 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:

   

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

5. Cercare quindi l'entità di sicurezza Azure Cosmos DB e selezionarla (per facilitarne l'individuazione, è anche possibile eseguire la ricerca in base all'ID applicazione: 00001111-aaaa-2222-bbbb-3333cccc4444 per tutte le aree di Azure ad eccezione delle aree di Azure per enti pubblici in cui l'ID applicazione è 11112222-bbbb-3333-cccc-4444dddd5555).

   Suggerimento

   In questo modo viene registrata l'identità di prima parte di Azure Cosmos DB nei criteri di accesso di Azure Key Vault. Se l'entità di sicurezza Azure Cosmos DB non è presente nell'elenco, potrebbe essere necessario registrare nuovamente il provider di risorse Microsoft.DocumentDB.

6. Scegliere Seleziona nella parte inferiore della schermata.

   

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

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

Aggiunta di ruoli di controllo degli accessi in base al ruolo

1. Dal portale di Azure passare all'istanza di Azure Key Vault che si intende usare per ospitare le chiavi di crittografia. Selezionare Controllo di accesso (IAM) dal menu a sinistra e scegliere Concedi accesso a questa risorsa.

   

   

2. Ricercare il ruolo di "Amministratore Key Vault" e assegnarlo a se stessi. Questa assegnazione viene eseguita cercando prima il nome del ruolo dall'elenco e quindi facendo clic sulla scheda "Membri". Nella scheda, selezionare l'opzione "Utente, gruppo o entità servizio", quindi cercare l'account Azure. Dopo aver selezionato l'account, è possibile assegnare il ruolo.

   

3. Le autorizzazioni necessarie devono quindi essere assegnate all'entità di sicurezza di Cosmos DB. Analogamente all'ultima assegnazione di ruolo, passare alla pagina di assegnazione, ma questa volta cercare il ruolo "Utente crittografia Crypto Service Key Vault" e nella scheda membri cercare l'entità di sicurezza di Cosmos DB. Per trovare l'entità di sicurezza, cercare l'entità di sicurezza di Azure Cosmos DB e selezionarla.

   

   Importante

   Nell'area di Azure per enti pubblici l'ID applicazione è 11112222-bbbb-3333-cccc-4444dddd5555.

4. Selezionare Rivedi e assegna e il ruolo verrà assegnato a Cosmos DB.

Verificare che i ruoli siano stati impostati correttamente

Usare quindi la pagina di controllo di accesso per verificare che tutti i ruoli siano stati configurati correttamente.

1. Dopo aver assegnato i ruoli, selezionare "Visualizza accesso a questa risorsa" nella pagina IAM di controllo di accesso per verificare che sia stato tutto impostato correttamente.

   

2. Nella pagina, impostare l'ambito su "questa risorsa" e verificare di avere il ruolo di amministratore Key Vault e che l'entità di sicurezza Cosmos DB abbia il ruolo Utente crittografia Crypto Key Vault.

Generare una chiave in Azure Key Vault

In questo caso, creare una nuova chiave usando Azure Key Vault e recuperare l'identificatore univoco.

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:

   

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:

   

   Suggerimento

   In alternativa, è possibile usare l'interfaccia della riga di comando di Azure per generare una chiave con:

   az keyvault key create \
       --vault-name <name-of-key-vault> \
       --name <name-of-key>
   

   Per altre informazioni sulla gestione di un insieme di credenziali delle chiavi con l'interfaccia della riga di comando di Azure, vedere Gestire Azure Key Vault con l'interfaccia della riga di comando di Azure.

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:

   

Creare un nuovo account Azure Cosmos DB

Creare un nuovo account Azure Cosmos DB usando il portale di Azure o l'interfaccia della riga di comando di Azure.

Azure portal

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:

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.

# 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  

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:

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

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:

# 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

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 copiato in precedenza nel parametro --key-uri.

# 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

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 \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "keyVaultKeyUri"

Importante

A seconda della configurazione di rete, potrebbe essere necessario consentire l'accesso ad Azure Cosmos DB da altri servizi di Azure.

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

Questi criteri di accesso garantiscono l’accesso alle chiavi di crittografia da parte dell'account Azure Cosmos DB. I criteri di accesso vengono implementati concedendo l'accesso a un'identità di Microsoft Entra 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.

Modello di Azure Resource Manager

È possibile usare i modelli di Resource Manager per assegnare un'identità gestita a un criterio di accesso.

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. 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'oggetto principalId assegnato.

2. Aggiungere le autorizzazioni corrispondenti all'account Azure Key Vault come descritto in precedenza. Anziché usare l'entità di sicurezza di Cosmos DB, usare l'oggetto principalId copiato nel passaggio precedente anziché l'identità 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 durante l'accesso alle chiavi di crittografia in Azure Key Vault.

   {
     "type": " Microsoft.DocumentDB/databaseAccounts",
     "properties": {
       "defaultIdentity": "SystemAssignedIdentity",
       // ...
     },
     // ...
   }
   

4. Facoltativamente, è possibile rimuovere l'identità di prima parte di Azure Cosmos DB dai criteri di accesso di Azure Key Vault.

È inoltre possibile seguire passaggi simili con un'identità gestita assegnata dall'utente.

1. Quando si creano i nuovi criteri di accesso o si esegue l'assegnazione di ruolo nell'account Azure Key Vault, usare il valore Object ID dell'identità 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.

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

Interfaccia della riga di comando di Azure

È possibile usare l'interfaccia della riga di comando di Azure per assegnare un'identità gestita a un criterio di accesso.

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. 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'oggetto principalId assegnato.

2. Aggiungere le autorizzazioni corrispondenti all'account Azure Key Vault come descritto in precedenza. Anziché usare l'entità di sicurezza di Cosmos DB, usare l'oggetto principalId copiato nel passaggio precedente anziché l'identità 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 durante l'accesso alle chiavi di crittografia in Azure Key Vault.

   # 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"
   

4. Facoltativamente, è possibile rimuovere l'identità di prima parte di Azure Cosmos DB dai criteri di accesso di Azure Key Vault.

È inoltre possibile seguire passaggi simili con un'identità gestita assegnata dall'utente.

1. Quando si creano i nuovi criteri di accesso o si esegue l'assegnazione di ruolo nell'account Azure Key Vault, usare il valore Object ID dell'identità 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.

   # 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"
   

PowerShell/portale di Azure

Non disponibile

Usare chiavi gestite dal cliente con il backup continuo

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

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

Dopo aver creato l'account, è possibile aggiornare l'identità in identità gestita assegnata dal sistema.

In alternativa, l'utente può anche creare prima un'identità di sistema con modalità di backup periodica, quindi eseguire la migrazione dell'account alla modalità di backup continuo seguendo queste istruzioni Eseguire la migrazione di un account Azure Cosmos DB dalla modalità di backup periodico a quello continuo

Interfaccia della riga di comando di Azure

# 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"

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 2021-11-15 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, 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>"
    // ...
  }
}

PowerShell/portale di Azure

Non disponibile

Ripristinare un account continuo configurato con l'identità gestita

Nella richiesta di ripristino è necessaria un'identità assegnata dall'utente perché l'identità gestita dell'account di origine (identità assegnate dall'utente e assegnate dal sistema) non può essere trasferita automaticamente nell’account del database di destinazione.

Interfaccia della riga di comando di Azure

Usare l'interfaccia della riga di comando di Azure per ripristinare un account continuo già configurato usando un'identità gestita assegnata dal sistema o assegnata dall'utente.

1. Creare una nuova identità assegnata dall'utente (o usarne una esistente) per il processo di ripristino.

2. Creare i nuovi criteri di accesso nell'account Azure Key Vault come descritto in precedenza, usare l'ID oggetto dell'identità gestita del passaggio 1.

3. Attivare il ripristino usando l'interfaccia della riga di comando di Azure:

   # 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" \
   

4. Al termine del ripristino, l'account di destinazione (ripristinato) ha l'identità assegnata dall'utente. Se necessario, l'utente può aggiornare l'account in modo da usare l'identità gestita assegnata dal sistema.

PowerShell / modello di Azure Resource Manager / portale di Azure

Non disponibile

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 doppia crittografia si applica solo all'archiviazione transazionale principale di Azure Cosmos DB. Alcune funzionalità implicano la replica interna dei dati in un secondo livello di archiviazione in cui non viene fornita la doppia crittografia, nemmeno con chiavi gestite dal cliente. Queste funzionalità sono:

• Azure Synapse Link
• Backup continui con ripristino temporizzato

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:

  

• Scambiare la chiave attualmente usata con un'altra aggiornando l'URI della chiave nell'account. Nel portale di Azure, accedere all'account Azure Cosmos DB e selezionare Crittografia dati dal menu a sinistra:

  

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

  

  Ecco come ottenere lo stesso risultato in PowerShell:

  # 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
  

La versione della chiave o la chiave precedente può essere disabilitata dopo che i log di controllo di Azure Key Vault non mostrano più l'attività di Azure Cosmos DB su tale versione della chiave o su tale chiave. Non dovrebbero essere eseguite altre attività sulla chiave o sulla versione della chiave precedente dopo 24 ore dalla rotazione delle chiavi.

La rotazione automatica delle chiavi in Azure Key Vault è supportata purché la chiave precedente non sia disabilitata o eliminata. I sistemi interni richiedono tempo per recuperare la nuova versione della chiave dopo aver verificato che l'account non sia in stato revocato o in transizione per abilitare le chiavi gestite dal cliente.

Gestione degli errori

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

Domande frequenti

Di seguito sono riportate le domande frequenti sulla configurazione delle chiavi gestite dal cliente in Azure Cosmos DB.

Sono previsti 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à?

Quando si usano le chiavi gestite dal cliente, le Unità richiesta utilizzate dalle operazioni del database registrano un aumento per riflettere l'elaborazione aggiuntiva necessaria per eseguire la crittografia e la decrittografia dei dati. Il consumo extra di UR può portare a un utilizzo leggermente superiore della capacità di cui è stato effettuato il provisioning. Utilizzare questa tabella 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 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?

Con le chiavi gestite dal cliente vengono crittografati tutti i dati archiviati nell'account Azure Cosmos DB tranne i metadati seguenti:

• Nomi di account, database e contenitori di Azure Cosmos DB

• Nomi delle stored procedure

• Percorsi delle proprietà dichiarati nei criteri di indicizzazione

• Valori delle chiavi di partizione dei contenitori

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

Sì. È possibile fare riferimento a Come configurare le chiavi gestite dal cliente per gli account Azure Cosmos DB esistenti

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

Sì, Collegamento ad Azure Synapse 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 nei criteri di accesso di Azure Key Vault prima di abilitare Collegamento ad Azure Synapse nell'account. Per una guida pratica su come abilitare l'identità gestita e usarla in criteri 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 usato?

Dal portale di Azure, accedere all'account Azure Cosmos DB e controllare la voce Crittografia dati nel menu a sinistra. Se questa voce è presente, le chiavi gestite dal cliente sono abilitate nell'account:

È possibile recuperare i dettagli dell'account Azure Cosmos DB anche a livello di codice e cercare la presenza della proprietà keyVaultKeyUri.

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.

Per ripristinare correttamente un backup periodico sono necessarie le condizioni seguenti:

• 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 effettuata 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 dipende dal fatto che 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 dai criteri di accesso di Key Vault.

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

Azure Cosmos DB offre la possibilità di configurare backup continui nell'account. Con i backup continui è possibile ripristinare i dati a qualsiasi momento entro gli ultimi 30 giorni. Per usare i backup continui in un account in cui sono abilitate le chiavi gestite dal cliente, è necessario usare un'identità gestita assegnata dal sistema o assegnata dall'utente nei criteri di accesso di Key Vault. Le identità proprietarie di Azure Cosmos DB non sono attualmente supportate negli account che usano backup continui.

Passaggi preliminari per gli account abilitati alle chiavi gestite dal cliente per aggiornare l'identità assegnata dall'utente.

• Aggiungere un'identità assegnata dall'utente all'account Cosmos DB e concedere le autorizzazioni nei criteri di accesso dell'insieme di credenziali delle chiavi.
• Impostare come predefinita l'identità assegnata dall'utente tramite l'interfaccia della riga di comando di Azure o ARM.

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

Per eseguire correttamente un ripristino temporizzato sono necessarie le condizioni seguenti:

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

Come si revoca una chiave di crittografia?

La revoca della chiave viene eseguita disabilitando la versione più recente della 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:

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.

Assegnare una nuova identità gestita all'account del database ripristinato per continuare ad accedere o ripristinare l'accesso all'account del database

L'identità assegnata dall'utente è associata a un account Cosmos DB specificato, ogni volta che si assegna a un account un'identità assegnata dall'utente, ARM inoltra la richiesta alle identità del servizio gestite per stabilire questa connessione. Attualmente vengono fornite informazioni sull'identità utente dall'account del database di origine all'account del database di destinazione durante il ripristino (sia per il ripristino di backup continuo che periodico) della chiave gestita dal cliente e dell’identità assegnata dall'utente.

Questo perché i metadati di identità sono associati all'account del database di origine e il flusso di lavoro di ripristino non rientra nell'ambito dell'identità per l'account del database di destinazione. Perciò gli account di database ripristinati saranno in uno stato non valido e diventeranno inaccessibili dopo l'eliminazione dell'account di origine e la scadenza del tempo di rinnovo dell'identità.

Passaggi per assegnare una nuova identità gestita:

1. Creare una nuova identità gestita assegnata dall'utente.
2. Concedere a questa identità l'accesso alla chiave KeyVault.
3. Assegnare questa nuova identità all'account del database ripristinato.

Passaggi successivi

• Altre informazioni sulla crittografia dei dati in Azure Cosmos DB.