Configure a chave gerida pelo cliente (CMK) para encriptação de dados em repouso para um cluster Azure DocumentDB

Neste artigo, aprende como configurar a chave gerida pelo cliente (CMK) para encriptação de dados em repouso no Azure DocumentDB. Os passos deste guia configuram um novo cluster Azure DocumentDB, um cluster réplica ou um cluster restaurado. A configuração da CMK usa a chave gerenciada pelo cliente armazenada em um Cofre de Chaves do Azure e a identidade gerenciada atribuída pelo usuário.

Pré-requisitos

• Uma assinatura do Azure

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita

• Utilize o ambiente Bash no Azure Cloud Shell. Para mais informações, veja Get started with Azure Cloud Shell.

  

• Se preferir executar comandos de referência da CLI localmente, instale o CLI do Azure. Se estiver a usar Windows ou macOS, considere executar o Azure CLI num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

  • Se você estiver usando uma instalação local, entre na CLI do Azure usando o comando az login . Para concluir o processo de autenticação, siga os passos exibidos no seu terminal. Para outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.

  • Quando solicitado, instale a extensão do Azure CLI na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a CLI do Azure.

  • Execute az version para descobrir a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.

Preparar a identidade gerenciada atribuída pelo usuário e o Cofre da Chave do Azure

Para configurar a encriptação de chaves gerida pelo cliente no seu Azure DocumentDB para o cluster MonogDB, precisa de uma identidade gerida atribuída pelo utilizador, de uma instância Azure Key Vault e das permissões devidamente configuradas.

Importante

A identidade gerida atribuída pelo utilizador e a instância Azure Key Vault usadas para configurar o CMK devem estar na mesma região Azure onde o cluster Azure DocumentDB está alojado e todas pertencem ao mesmo tenant Microsoft.

Usando o portal do Azure:

1. Crie uma identidade gerenciada atribuída pelo usuário na região do cluster, se ainda não tiver uma.

2. Crie um Cofre da Chave do Azure na região do cluster, se ainda não tiver um armazenamento de chaves criado. Certifique-se de que cumpre os requisitos. Além disso, siga as recomendações antes de configurar o armazenamento de chaves e antes de criar a chave e atribuir as permissões necessárias à identidade gerenciada atribuída pelo usuário.

3. Crie uma chave no seu armazenamento de chaves.

4. Conceda permissões de identidade gerenciada atribuídas pelo usuário à instância do Cofre da Chave do Azure, conforme descrito nos requisitos.

Configurar a criptografia de dados com chave gerenciada pelo cliente durante o provisionamento de cluster

Portal

1. Durante o provisionamento de um novo cluster Azure DocumentDB, chaves geridas por serviços ou pelo cliente para encriptação de dados do cluster são configuradas no separador Encryption . Selecione a chave gerida pelo cliente para encriptação de dados.

   

2. Na seção Identidade gerenciada atribuída pelo usuário , selecione Alterar identidade.

   

3. Na lista de identidades gerenciadas atribuídas pelo usuário, selecione aquela que você deseja que seu cluster use para acessar a chave de criptografia de dados armazenada em um Cofre de Chaves do Azure.

   

4. Selecione Adicionar.

   

5. No método de seleção de chaves, escolha Selecionar uma chave .

6. Na seção Chave , selecione Alterar chave .

   

7. No painel Selecionar uma chave , selecione o Cofre da Chave do Azure no Cofre da Chave e a chave de criptografia na Chave e confirme suas escolhas selecionando Selecionar.

   

   Importante

   A instância selecionada do Azure Key Vault deve estar na mesma região Azure onde o cluster Azure DocumentDB vai ser alojado.

8. Confirme a identidade gerenciada atribuída pelo usuário selecionada e a chave de criptografia na guia Criptografia e selecione Revisar + criar para criar cluster.

   

APIs REST

Você pode habilitar a criptografia de dados com a chave de criptografia atribuída pelo usuário, enquanto provisiona um novo cluster, por meio de um az rest comando.

1. Crie um arquivo JSON com o seguinte conteúdo. Substitua os espaços reservados que começam com $ sinal pelos valores reais e salve o arquivo.

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

   Observação

   O keyEncryptionKeyUrl deve conter o nome da chave, mas não deve conter uma versão de chave específica.

2. Execute o seguinte comando Azure CLI para fazer uma chamada REST API para criar um cluster Azure DocumentDB. Substitua os espaços reservados na seção de variáveis e o nome do arquivo para o --body parâmetro na linha de az rest comando pelos valores reais.

   # 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
   

Atualizar configurações de criptografia de dados no cluster com CMK habilitada

Para clusters existentes que foram implantados com criptografia de dados usando uma chave gerenciada pelo cliente, você pode fazer várias alterações de configuração. Você pode alterar o cofre de chaves onde a chave de criptografia está armazenada e a chave de criptografia usada como uma chave gerenciada pelo cliente. Você também pode alterar a identidade gerenciada atribuída pelo usuário usada pelo serviço para acessar a chave de criptografia mantida no armazenamento de chaves.

Portal

1. Na barra lateral do cluster, em Configurações, selecione Criptografia de dados.

2. Na seção Identidade gerenciada atribuída pelo usuário , selecione Alterar identidade.

   

3. Na lista de identidades gerenciadas atribuídas pelo usuário, selecione aquela que você deseja que seu cluster use para acessar a chave de criptografia de dados armazenada em um Cofre de Chaves do Azure.

   

4. Selecione Adicionar.

5. No método de seleção de chaves, escolha Selecionar uma chave .

6. Na Chave, escolha Alterar chave.

   

7. No painel Selecionar uma chave , selecione o Cofre da Chave do Azure no Cofre da Chave e a chave de criptografia na Chave e confirme suas escolhas selecionando Selecionar.

   

   Importante

   Uma instância selecionada do Azure Key Vault deve estar na mesma região Azure onde o cluster Azure DocumentDB está alojado.

8. Confirme a identidade gerenciada atribuída pelo usuário selecionada e a chave de criptografia na página Criptografia de dados e selecione Salvar para confirmar suas seleções e criar um cluster de réplica.

   

APIs REST

Você pode alterar a identidade gerenciada atribuída pelo usuário e a chave de criptografia para criptografia de dados em um cluster existente por meio de uma chamada de API REST.

1. Crie um arquivo JSON com o seguinte conteúdo. Substitua os espaços reservados que começam com $ sinal pelos valores reais e salve o arquivo.

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

   Observação

   O keyEncryptionKeyUrl deve conter o nome da chave, mas não deve conter uma versão de chave específica.

2. Execute o seguinte comando Azure CLI para fazer uma chamada REST API para criar um cluster Azure DocumentDB. Substitua os espaços reservados na seção de variáveis e o nome do arquivo para o --body parâmetro na linha de az rest comando pelos valores reais.

   # 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 você deseja alterar apenas a identidade gerenciada atribuída pelo usuário usada para acessar a chave, ou se deseja alterar apenas a chave usada para criptografia de dados, ou se deseja alterar ambos ao mesmo tempo, é necessário fornecer todos os parâmetros listados no arquivo JSON.

Se a chave ou a identidade gerenciada atribuída pelo usuário especificada não existirem, você receberá o erro.

As identidades passadas como parâmetros, se existirem e forem válidas, são automaticamente adicionadas à lista de identidades geridas atribuídas pelo utilizador associadas ao seu cluster Azure DocumentDB. Este é o caso, mesmo se o comando mais tarde falhar com algum outro erro.

Alterar o modo de criptografia de dados em clusters existentes

O único ponto em que você pode decidir se deseja usar uma chave gerenciada por serviço ou uma chave gerenciada pelo cliente (CMK) para criptografia de dados é no momento da criação do cluster. Depois de tomar essa decisão e criar o cluster, você não pode alternar entre as duas opções. Para criar uma cópia do seu cluster Azure DocumentDB com uma opção de encriptação diferente, pode criar um cluster réplica ou realizar uma restauração do cluster e selecionar o novo modo de encriptação durante a criação do cluster réplica ou do cluster restaurado.

Habilitar ou desabilitar a criptografia de dados de chave gerenciada pelo cliente (CMK) durante a criação do cluster de réplica

Siga estas etapas para criar um cluster de réplica com criptografia de dados CMK ou SMK para habilitar ou desabilitar a CMK em um cluster de réplica.

Portal

1. Na barra lateral do cluster, em Configurações, selecione Distribuição global.

2. Selecione Adicionar nova réplica de leitura.

   

3. Forneça um nome de cluster de réplica no campo Ler nome da réplica.

4. Selecione uma região na Região da réplica de leitura. O cluster de réplica é hospedado na região selecionada do Azure.

   Observação

   O cluster de réplica é sempre criado no mesmo grupo de recursos e assinatura do Azure que seu cluster primário (leitura-gravação).

   

5. Na seção Criptografia de dados , selecione a chave gerenciada pelo cliente para habilitar a CMK ou a chave gerenciada pelo serviço para desabilitar a CMK no cluster de réplica.

   

6. Na seção Identidade gerenciada atribuída pelo usuário , selecione Alterar identidade.

   

7. Na lista de identidades gerenciadas atribuídas pelo usuário, selecione aquela que você deseja que seu cluster use para acessar a chave de criptografia de dados armazenada em um Cofre de Chaves do Azure.

   

8. Selecione Adicionar.

9. No método de seleção de chaves, escolha Selecionar uma chave .

10. Na Chave, escolha Alterar chave.

    

11. No painel Selecionar uma chave , selecione o Cofre da Chave do Azure no Cofre da Chave e a chave de criptografia na Chave e confirme suas escolhas selecionando Selecionar.

    

12. Confirme a identidade gerenciada atribuída pelo usuário selecionada e a chave de criptografia na página Distribuição global e selecione Salvar para confirmar suas seleções e criar cluster de réplica.

    

APIs REST

Para criar um cluster de réplica com CMK habilitada na mesma região, siga estas etapas.

1. Crie um arquivo JSON com o seguinte conteúdo. Substitua os espaços reservados que começam com $ sinal pelos valores reais e salve o arquivo.

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

   Observação

   O keyEncryptionKeyUrl deve conter o nome da chave, mas não deve conter uma versão de chave específica.

2. Execute o seguinte comando Azure CLI para fazer uma chamada REST API para criar um cluster Azure DocumentDB. Substitua os espaços reservados na seção de variáveis e o nome do arquivo para o --body parâmetro na linha de az rest comando pelos valores reais.

   # 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
   

Habilite ou desabilite a criptografia de dados de chave gerenciada pelo cliente (CMK) durante a restauração do cluster

O processo de restauração cria um novo cluster com a mesma configuração na mesma região, assinatura e grupo de recursos do Azure que o original. Siga estas etapas para criar um cluster restaurado com CMK ou SMK habilitado.

Portal

1. Selecione um cluster Azure DocumentDB existente.

2. Na barra lateral do cluster, em Configurações, selecione Restauração no Tempo.

3. Selecione uma data e forneça uma hora (no fuso horário UTC) nos campos de data e hora.

   

4. Insira um nome de cluster no campo Restaurar nome do cluster de destino .

   

5. Insira um nome de administrador de cluster para o cluster restaurado no campo Nome de usuário de administrador .

6. Introduza uma palavra-passe para a função de administrador nos campos Palavra-passe e Confirmar palavra-passe .

   

7. Na seção Criptografia de dados , selecione a chave gerenciada pelo cliente para habilitar a CMK. Se você precisar ter a CMK desabilitada no cluster restaurado, selecione Chave gerenciada pelo serviço.

   

8. Na seção Identidade gerenciada atribuída pelo usuário , selecione Alterar identidade.

   

9. Na lista de identidades gerenciadas atribuídas pelo usuário, selecione aquela que você deseja que seu cluster use para acessar a chave de criptografia de dados armazenada em um Cofre de Chaves do Azure.

   

10. Selecione Adicionar.

11. No método de seleção de chaves, escolha Selecionar uma chave .

12. Na Chave, escolha Alterar chave.

    

13. No painel Selecionar uma chave , selecione o Cofre da Chave do Azure no Cofre da Chave e a chave de criptografia na Chave e confirme suas escolhas selecionando Selecionar.

    

14. Selecione Enviar para iniciar a restauração do cluster.

APIs REST

Para restaurar um cluster com CMK habilitada, siga estas etapas.

1. Crie um arquivo JSON com o seguinte conteúdo. Substitua os espaços reservados que começam com $ sinal pelos valores reais e salve o arquivo.

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

   Observação

   O keyEncryptionKeyUrl deve conter o nome da chave, mas não deve conter uma versão de chave específica.

2. Execute o seguinte comando Azure CLI para fazer uma chamada REST API para criar um cluster Azure DocumentDB. Substitua os espaços reservados na seção de variáveis e o nome do arquivo para o --body parâmetro na linha de az rest comando pelos valores reais.

   # 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
   

Depois que o cluster restaurado for criado, revise a lista de tarefas pós-restauração.

Conteúdo relacionado

• Aprenda sobre encriptação de dados em repouso no Azure DocumentDB
• Solucionar problemas de configuração da CMK
• Confira as limitações da CMK
• Migrate data to Azure DocumentDB