Configurare la chiave gestita dal cliente (CMK) per la crittografia dei dati inattivi per un cluster di Azure DocumentDB

Questo articolo illustra come configurare la chiave gestita dal cliente (CMK) per la crittografia dei dati inattivi in Azure DocumentDB. I passaggi descritti in questa guida consentono di configurare un nuovo cluster di Azure DocumentDB, un cluster di replica o un cluster ripristinato. La configurazione della chiave gestita dal cliente usa una chiave gestita dal cliente archiviata in un insieme di credenziali delle chiavi di Azure e un'identità gestita assegnata dall'utente.

Prerequisiti

• Una sottoscrizione di Azure

  • Se non hai un abbonamento Azure, crea un account gratuito

• È possibile utilizzare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad Azure Cloud Shell.

  

• Se preferisci eseguire localmente i comandi di riferimento della CLI, installa l'Azure CLI. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

  • Se usi un'installazione locale, accedi all'interfaccia della riga di comando di Azure usando il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.

  • Quando ti viene richiesto, installa l'estensione Azure CLI al primo utilizzo. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con l'interfaccia della riga di comando di Azure.

  • Esegui az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, avviare az upgrade.

Preparare l'identità gestita assegnata dall'utente e Azure Key Vault

Per configurare la crittografia della chiave gestita dal cliente nel cluster Azure DocumentDB per MonogDB, è necessaria un'identità gestita assegnata dall'utente, un'istanza di Azure Key Vault e autorizzazioni configurate correttamente.

Importante

L'identità gestita assegnata dall'utente e l'istanza di Azure Key Vault usata per configurare cmk devono trovarsi nella stessa area di Azure in cui è ospitato il cluster Azure DocumentDB e tutti appartengono allo stesso tenant Microsoft.

Usare il portale di Azure:

1. Creare un'identità gestita assegnata dall'utente nell'area del cluster, se non ne è ancora disponibile una.

2. Creare un Azure Key Vault nell'area del cluster, se non è ancora stato creato un archivio di chiavi. Assicurarsi di soddisfare i requisiti. Seguire anche i consigli prima di configurare l'archivio di chiavi e prima di creare la chiave e assegnare le autorizzazioni necessarie all'identità gestita assegnata dall'utente.

3. Creare una chiave nell'archivio chiavi.

4. Concedere autorizzazioni di identità gestite assegnate dall'utente all'istanza di Azure Key Vault come descritto nei requisiti.

Configurare la crittografia dei dati con la chiave gestita dal cliente durante il provisioning del cluster

Portal

1. Durante il provisioning di un nuovo cluster di Azure DocumentDB, le chiavi gestite dal servizio o dal cliente per la crittografia dei dati del cluster vengono configurate nella scheda Crittografia. Selezionare la chiave gestita dal cliente per la crittografia dei dati.

   

2. Nella sezione Identità gestita assegnata dall'utente, selezionare Cambia identità.

   

3. Nell'elenco delle identità gestite assegnate dall'utente selezionare quella che il cluster deve usare per accedere alla chiave di crittografia dei dati archiviata in un Azure Key Vault.

   

4. Seleziona Aggiungi.

   

5. Nel metodo di selezione chiave, scegliere Seleziona una chiave.

6. Nella sezione Chiave, selezionare Cambia chiave.

   

7. Nel riquadro Selezionare una chiave, selezionare l'insieme di credenziali delle chiavi di Azure in Insieme di credenziali delle chiavi e la chiave di crittografia in Chiave e confermare le scelte selezionando Seleziona.

   

   Importante

   L'istanza di Azure Key Vault selezionata deve trovarsi nella stessa area di Azure in cui verrà ospitato il cluster Azure DocumentDB.

8. Confermare l'identità gestita assegnata dall'utente e la chiave di crittografia selezionata nella scheda Crittografia e selezionare Rivedi e crea per creare il cluster.

   

API REST

È possibile abilitare la crittografia dei dati con la chiave di crittografia assegnata dall'utente durante il provisioning di un nuovo cluster tramite un comando az rest.

1. Creare un file JSON con il seguente contenuto. Sostituire i segnaposto che iniziano con il segno $ con i valori effettivi e salvare il file.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "administrator": {
             "userName": "$adminName",
             "password": "$complexPassword"
           },
           "serverVersion": "8.0",
           "storage": {
             "sizeGb": 32
           },
           "compute": {
             "tier": "M40"
           },
           "sharding": {
             "shardCount": 1
           },
           "highAvailability": {
             "targetMode": "ZoneRedundantPreferred"
           },
         "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   Annotazioni

   keyEncryptionKeyUrl deve contenere il nome della chiave, ma non deve contenere una versione della chiave specifica.

2. Eseguire il seguente comando Azure CLI per eseguire una chiamata API REST e creare un cluster di Azure DocumentDB. Sostituire i segnaposto nella sezione variabili e il nome del file per il --body parametro nella az rest riga di comando con i valori effettivi.

   # Define your variables
   $randomIdentifier = (New-Guid).ToString().Substring(0,8)
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="DocumentDB"
   $mongoClustersName="msdocscr$randomIdentifier"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Aggiornare le impostazioni di crittografia dei dati nel cluster con CMK abilitato

Per i cluster esistenti distribuiti con la crittografia dei dati usando una chiave gestita dal cliente, è possibile apportare diverse modifiche alla configurazione. È possibile modificare l'insieme di credenziali delle chiavi in cui è archiviata la chiave di crittografia e la chiave di crittografia usata come chiave gestita dal cliente. È anche possibile modificare l'identità gestita assegnata dall'utente usata dal servizio per accedere alla chiave di crittografia mantenuta nell'archivio chiavi.

Portal

1. Nella barra laterale del cluster, in Impostazioni, selezionare Crittografia dati.

2. Nella sezione Identità gestita assegnata dall'utente, selezionare Cambia identità.

   

3. Nell'elenco delle identità gestite assegnate dall'utente selezionare quella che il cluster deve usare per accedere alla chiave di crittografia dei dati archiviata in un Azure Key Vault.

   

4. Seleziona Aggiungi.

5. Nel metodo di selezione chiave, scegliere Seleziona una chiave.

6. In Chiave, scegliere Cambia chiave.

   

7. Nel riquadro Selezionare una chiave, selezionare l'insieme di credenziali delle chiavi di Azure in Insieme di credenziali delle chiavi e la chiave di crittografia in Chiave e confermare le scelte selezionando Seleziona.

   

   Importante

   L'istanza di Azure Key Vault selezionata deve trovarsi nella stessa area di Azure in cui è ospitato il cluster Azure DocumentDB.

8. Confermare l'identità gestita assegnata dall'utente e la chiave di crittografia selezionata nella pagina Crittografia dei dati e selezionare Salva per confermare le selezioni e creare il cluster di replica.

   

API REST

È possibile modificare l'identità gestita assegnata dall'utente e la chiave di crittografia per la crittografia dei dati in un cluster esistente tramite una chiamata API REST.

1. Creare un file JSON con il seguente contenuto. Sostituire i segnaposto che iniziano con il segno $ con i valori effettivi e salvare il file.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   Annotazioni

   keyEncryptionKeyUrl deve contenere il nome della chiave, ma non deve contenere una versione della chiave specifica.

2. Eseguire il seguente comando CLI di Azure per effettuare una chiamata API REST per creare un cluster di Azure DocumentDB. Sostituire i segnaposto nella sezione variabili e il nome del file per il --body parametro nella az rest riga di comando con i valori effettivi.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Se si vuole modificare solo l'identità gestita assegnata dall'utente usata per accedere alla chiave o se si vuole solo modificare la chiave usata per la crittografia dei dati, oppure modificare entrambi contemporaneamente, è necessario specificare tutti i parametri elencati nel file JSON.

Se la chiave o l'identità gestita assegnata dall'utente specificata non esistono, viene visualizzato l'errore.

Le identità passate come parametri, se esistenti e valide, vengono aggiunte automaticamente all'elenco delle identità gestite assegnate dall'utente associate al cluster Azure DocumentDB. Questo è il caso anche se il comando in un secondo momento ha esito negativo con un altro errore.

Modificare la modalità di crittografia dei dati nei cluster esistenti

L'unico punto in cui è possibile decidere se si vuole usare una chiave gestita dal servizio o una chiave gestita dal cliente per la crittografia dei dati è in fase di creazione del cluster. Dopo aver deciso e creato il cluster, non è possibile passare tra le due opzioni. Per creare una copia del cluster Azure DocumentDB con un'opzione di crittografia diversa, è possibile creare un cluster di replica oppure eseguire un ripristino del cluster e selezionare la nuova modalità di crittografia durante la creazione del cluster di replica o del cluster ripristinato.

Abilitare o disabilitare la crittografia dei dati della chiave gestita dal cliente durante la creazione del cluster di replica

Seguire questa procedura per creare un cluster di replica con la crittografia dei dati CMK o SMK per abilitare o disabilitare la chiave gestita dal cliente in un cluster di replica.

Portal

1. Nella barra laterale del cluster, in Impostazioniselezionare Distribuzione globale.

2. Selezionare Aggiungi nuova replica di lettura.

   

3. Specificare un nome del cluster di replica nel campo del nome Replica di lettura.

4. Selezionare un'area nell'Area della replica di lettura. Il cluster di replica è ospitato nell'area di Azure selezionata.

   Annotazioni

   Il cluster di replica viene sempre creato nella stessa sottoscrizione di Azure e nello stesso gruppo di risorse del cluster primario (lettura/scrittura).

   

5. Nella sezione Crittografia dati, selezionare Chiave gestita dal cliente per abilitare la chiave gestita dal cliente o Chiave gestita dal servizio per disabilitare la chiave gestita dal cliente nel cluster di replica.

   

6. Nella sezione Identità gestita assegnata dall'utente, selezionare Cambia identità.

   

7. Nell'elenco delle identità gestite assegnate dall'utente selezionare quella che il cluster deve usare per accedere alla chiave di crittografia dei dati archiviata in un Azure Key Vault.

   

8. Seleziona Aggiungi.

9. Nel metodo di selezione chiave, scegliere Seleziona una chiave.

10. In Chiave, scegliere Cambia chiave.

    

11. Nel riquadro Selezionare una chiave, selezionare l'insieme di credenziali delle chiavi di Azure in Insieme di credenziali delle chiavi e la chiave di crittografia in Chiave e confermare le scelte selezionando Seleziona.

    

12. Confermare l'identità gestita assegnata dall'utente e la chiave di crittografia selezionata nella pagina Distribuzione globale e selezionare Salva per confermare le selezioni e creare il cluster di replica.

    

API REST

Per creare un cluster di replica con chiave gestita dal cliente abilitata nella stessa area, seguire questa procedura.

1. Creare un file JSON con il seguente contenuto. Sostituire i segnaposto che iniziano con il segno $ con i valori effettivi e salvare il file.

   {
           "identity": {
               "type": "UserAssigned",
               "userAssignedIdentities": {
                 "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
               }
             },
         "location": "$targetRegionName",
             "properties": {
             	"createMode": "GeoReplica",
                   "replicaParameters": {
                     "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$sourceClusterName",
                     "sourceLocation": "sourceRegionName"
                   },
                   "encryption": {
                     "customerManagedKeyEncryption": {
                       "keyEncryptionKeyIdentity": {
                         "identityType": "UserAssignedIdentity",
                         "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                       },
                       "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                     }
                   }
             }
       }
   

   Annotazioni

   keyEncryptionKeyUrl deve contenere il nome della chiave, ma non deve contenere una versione della chiave specifica.

2. Esegui il seguente comando CLI di Azure per effettuare una chiamata API REST e creare un cluster Azure DocumentDB. Sostituire i segnaposto nella sezione variabili e il nome del file per il --body parametro nella az rest riga di comando con i valori effettivi.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Abilitare o disabilitare la crittografia dei dati della chiave gestita dal cliente durante il ripristino del cluster

Il processo di ripristino crea un nuovo cluster con la stessa configurazione nella stessa area di Azure, nella stessa sottoscrizione e nello stesso gruppo di risorse dell'originale. Seguire questa procedura per creare un cluster ripristinato con CMK o SMK abilitato.

Portal

1. Selezionare un cluster Di Azure DocumentDB esistente.

2. Nella barra laterale del cluster, in Impostazioni, selezionare Ripristino temporizzato.

3. Selezionare una data e specificare un'ora (nel fuso orario UTC) nei campi data e ora.

   

4. Immettere un nome del cluster nel campo Ripristina nome cluster di destinazione.

   

5. Immettere un nome amministratore del cluster per il cluster ripristinato nel campo Nome utente amministratore.

6. Immettere una password per il ruolo di amministratore nei campi Password e Conferma password.

   

7. Nella sezione Crittografia dati, selezionare la Chiave gestita dal cliente per abilitare la chiave gestita dal cliente. Nel caso in cui sia necessario disabilitare la chiave gestita dal cliente nel cluster ripristinato, selezionare Chiave gestita dal servizio.

   

8. Nella sezione Identità gestita assegnata dall'utente, selezionare Cambia identità.

   

9. Nell'elenco delle identità gestite assegnate dall'utente selezionare quella che il cluster deve usare per accedere alla chiave di crittografia dei dati archiviata in un Azure Key Vault.

   

10. Seleziona Aggiungi.

11. Nel metodo di selezione chiave, scegliere Seleziona una chiave.

12. In Chiave, scegliere Cambia chiave.

    

13. Nel riquadro Selezionare una chiave, selezionare l'insieme di credenziali delle chiavi di Azure in Insieme di credenziali delle chiavi e la chiave di crittografia in Chiave e confermare le scelte selezionando Seleziona.

    

14. Selezionare Invia per avviare il ripristino del cluster.

API REST

Per ripristinare un cluster con chiave gestita dal cliente abilitata, seguire questa procedura.

1. Creare un file JSON con il seguente contenuto. Sostituire i segnaposto che iniziano con il segno $ con i valori effettivi e salvare il file.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
               "administrator": {
                 "userName": "$adminName"
               },
         	"createMode": "PointInTimeRestore",
               "restoreParameters": {
                 "pointInTimeUTC": "yyyy-mm-ddThh:mm:ssZ",
                 "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$restoredClusterName"
               },
               "encryption": {
                 "customerManagedKeyEncryption": {
                   "keyEncryptionKeyIdentity": {
                     "identityType": "UserAssignedIdentity",
                     "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                   },
                   "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                 }
               }
         }
   }
   

   Annotazioni

   keyEncryptionKeyUrl deve contenere il nome della chiave, ma non deve contenere una versione della chiave specifica.

2. Eseguire il seguente comando dell'interfaccia della riga di comando di Azure per eseguire una chiamata API REST e creare un cluster di Azure DocumentDB. Sostituire i segnaposto nella sezione variabili e il nome del file per il --body parametro nella az rest riga di comando con i valori effettivi.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Dopo aver creato il cluster ripristinato, esaminare l'elenco delle attività di post-ripristino.

Contenuti correlati

• Informazioni sulla crittografia dei dati a riposo in Azure DocumentDB
• Risolvere i problemi di configurazione della chiave gestita dal cliente
• Vedere Limitazioni della chiave gestita dal cliente
• Eseguire la migrazione dei dati ad Azure DocumentDB