Configurar chaves gerenciadas pelo cliente para sua conta do Azure Cosmos DB com o Azure Key Vault

2025-07-08

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Tabela

Os dados armazenados em sua conta do Azure Cosmos DB são automaticamente e perfeitamente criptografados com chaves gerenciadas pela Microsoft (chaves gerenciadas pelo serviço). Opcionalmente, você pode optar por adicionar uma segunda camada de criptografia com chaves gerenciadas pelo cliente (chaves gerenciadas pelo cliente ou CMK).

Diagrama das camadas de criptografia em torno dos dados do cliente.

Você deve armazenar chaves gerenciadas pelo cliente no Cofre de Chaves do Azure e fornecer uma chave para cada conta do Azure Cosmos DB habilitada com chaves gerenciadas pelo cliente. Esta chave é utilizada para encriptar todos os dados armazenados nessa conta.

Nota

Se você deseja habilitar chaves gerenciadas pelo cliente em suas contas existentes do Azure Cosmos DB, consulte Configurar chaves gerenciadas pelo cliente para sua conta existente do Azure Cosmos DB com o Azure Key Vault.

Aviso

Os seguintes nomes de campo são reservados nas tabelas da API Cassandra em contas que usam chaves gerenciadas pelo cliente:

id
ttl
_ts
_etag
_rid
_self
_attachments
_epk

Quando as chaves gerenciadas pelo cliente não estão habilitadas, apenas os nomes de campo que começam com __sys_ são reservados.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.

Registrar o provedor de recursos do Azure Cosmos DB

Se o provedor de recursos Microsoft.DocumentDB ainda não estiver registrado, você deverá registrar esse provedor como uma primeira etapa.

Entre no portal do Azure, vá para sua assinatura do Azure e selecione Provedores de recursos na guia Configurações:
Pesquisa o provedor de recurso Microsoft.DocumentDB. Verifique se o provedor de recursos já está marcado como registrado. Caso contrário, escolha o provedor de recursos e selecione Registrar:

Configurar sua instância do Azure Key Vault

Importante

Sua instância do Azure Key Vault deve estar acessível por meio de acesso à rede pública ou permitir que serviços confiáveis da Microsoft ignorem seu firewall. Uma instância que é exclusivamente acessível por meio de pontos de extremidade privados não pode ser usada para hospedar suas chaves gerenciadas pelo cliente.

É altamente recomendável que o recurso Azure Key Vault criado tenha a replicação de dados habilitada para garantir a disponibilidade contínua durante interrupções regionais inesperadas.

O uso de chaves gerenciadas pelo cliente com o Azure Cosmos DB exige que você defina duas propriedades na instância do Cofre de Chaves do Azure que planeja usar para hospedar suas chaves de criptografia: Soft Delete e Purge Protection.

Se você criar uma nova instância do Azure Key Vault, habilite estas propriedades durante a criação:

Se estiver a utilizar uma instância existente do Azure Key Vault, pode verificar se estas propriedades estão ativadas consultando a secção Propriedades no portal do Azure. Se alguma dessas propriedades não estiver ativada, consulte as seções Ativação da eliminação suave e Ativação da proteção contra eliminação em um dos artigos seguintes:

Escolha o modelo de segurança preferido

Depois que a proteção contra limpeza e a exclusão suave estiverem habilitadas, na guia política de acesso, você poderá escolher seu modelo de permissão preferido para usar. As políticas de acesso são definidas por padrão, mas o controle de acesso baseado em função do Azure também é suportado.

As permissões necessárias devem ser dadas para permitir que o Cosmos DB use sua chave de criptografia. Esta etapa varia dependendo se o Cofre da Chave do Azure está usando políticas de acesso ou controle de acesso baseado em função.

Nota

É importante observar que apenas um modelo de segurança pode estar ativo de cada vez, portanto, não há necessidade de configurar o controle de acesso baseado em funções se o Azure Key Vault estiver definido para usar políticas de acesso e vice-versa.

Adicionar uma política de acesso

Nessa variação, use a entidade de segurança do Azure Cosmos DB para criar uma política de acesso com as permissões apropriadas.

No portal do Azure, vá para a instância do Cofre de Chaves do Azure que você planeja usar para hospedar suas chaves de criptografia. Selecione Políticas de Acesso no menu à esquerda:

Captura de ecrã da opção Políticas do Access no menu de navegação de recursos.

Selecione + Adicionar Política de Acesso.
No menu suspenso Permissões de chave, selecione Get, Unwrap Key e Wrap Key permissions:

Em Selecionar entidade de segurança, selecione Nenhuma selecionada.
Procure por Azure Cosmos DB principal e selecione-o.

Gorjeta

Isso registra a identidade de primeira parte do Azure Cosmos DB em sua política de acesso ao Cofre da Chave do Azure. Se a entidade Azure Cosmos DB não estiver na lista, talvez seja necessário re-registar o provedor de recursos Microsoft.DocumentDB.
Escolha Selecionar na parte inferior.
Selecione Adicionar para adicionar a nova política de acesso.
Selecione Salvar na instância do Cofre da Chave para salvar todas as alterações.

Adicionar funções de controle de acesso baseadas em função

No portal do Azure, vá para a instância do Cofre de Chaves do Azure que você planeja usar para hospedar suas chaves de criptografia. Selecione Controle de acesso (IAM) no menu à esquerda e selecione Conceder acesso a este recurso.
Pesquise a função de Administrador do Cofre de Chaves e atribua-a a si mesmo. Essa atribuição é feita pesquisando primeiro o nome da função na lista e, em seguida, clicando na guia Membros . Uma vez na guia, selecione a opção Usuário, grupo ou entidade de serviço no rádio e procure sua conta do Azure. Uma vez selecionada a conta, a função pode ser atribuída.
Em seguida, as permissões necessárias devem ser atribuídas ao principal do Cosmos DB. Então, como na última atribuição de função, vá para a página de atribuição, mas desta vez procure a função Usuário do Serviço de Criptografia do Cofre de Chaves e, na guia Membros, encontre o principal do Cosmos DB. Para encontrar a entidade, procure a entidade principal do Azure Cosmos DB e selecione-a.
Selecione Rever + atribuir e a função é atribuída ao Cosmos DB.

Validar se as funções estão definidas corretamente

Em seguida, use a página de controle de acesso para confirmar se todas as funções estão configuradas corretamente.

Depois que as funções forem atribuídas, selecione Exibir acesso a este recurso na página do IAM de controle de acesso para verificar se tudo está definido corretamente.
Na página, defina o escopo para este recurso e verifique se você tem a função de Administrador do Key Vault e se a entidade do Cosmos DB tem a função de Usuário de Cripto do Key Vault.

Gerar uma chave no Azure Key Vault

Aqui, crie uma nova chave usando o Azure Key Vault e recupere o identificador exclusivo.

No portal do Azure, vá para a instância do Cofre da Chave do Azure que você planeja usar para hospedar suas chaves de criptografia. Em seguida, selecione Teclas no menu à esquerda:
Selecione Gerar/Importar, forneça um nome para a nova chave e selecione um tamanho de chave RSA. Um mínimo de 3072 é recomendado para melhor segurança. Em seguida, selecione Criar:
Gorjeta

Como alternativa, você pode usar a CLI do Azure para gerar uma chave com:
```
az keyvault key create \
    --vault-name <name-of-key-vault> \
    --name <name-of-key>
```
Para obter mais informações sobre como gerenciar um cofre de chaves com a CLI do Azure, consulte gerenciar o Cofre da Chave do Azure com a CLI do Azure.
Depois que a chave for criada, selecione a chave recém-criada e, em seguida, sua versão atual.
Copie o Identificador de Chave da chave, exceto a parte após a última barra:

Criar uma nova conta do Azure Cosmos DB

Crie uma nova conta do Azure Cosmos DB usando o portal do Azure ou a CLI do Azure.

Ao criar uma nova conta do Azure Cosmos DB no portal do Azure, escolha Chave gerenciada pelo cliente na etapa Criptografia . No campo URI da chave, cole o identificador de URI/chave da chave do Cofre da Chave do Azure que você copiou da etapa anterior:

Quando você cria uma nova conta do Azure Cosmos DB com o PowerShell:

Passe o URI da chave do Cofre de Chaves do Azure copiada anteriormente na propriedade keyVaultKeyUri em PropertyObject.
Use 2019-12-12 ou posterior como a versão da API.

Importante

Você deve definir a locations propriedade explicitamente para que a conta seja criada com êxito com chaves gerenciadas pelo cliente.

# 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

Depois que a conta for criada, você poderá verificar se as chaves gerenciadas pelo cliente foram habilitadas buscando o URI da chave do Cofre de Chaves do Azure:

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

Quando você cria uma nova conta do Azure Cosmos DB por meio de um modelo do Azure Resource Manager (ARM):

Passe a URL da chave do Azure Key Vault que copiaste anteriormente na propriedade keyVaultKeyUri no objeto properties.
Use 2019-12-12 ou posterior como a versão da API.

Importante

Você deve definir a locations propriedade explicitamente para que a conta seja criada com êxito com chaves gerenciadas pelo cliente.

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

Implante o modelo com o seguinte script do PowerShell:

# 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

Quando você cria uma nova conta do Azure Cosmos DB por meio da CLI do Azure, passe o URI da chave do Cofre da Chave do Azure que você copiou anteriormente no --key-uri parâmetro.

# 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

Depois que a conta for criada, você poderá verificar se as chaves gerenciadas pelo cliente foram habilitadas buscando o URI da chave do Cofre de Chaves do Azure:

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

Importante

Dependendo da sua configuração de rede, talvez seja necessário permitir o acesso ao Azure Cosmos DB de outros serviços do Azure.

Usando uma identidade gerenciada na política de acesso do Cofre da Chave do Azure

Essa política de acesso garante que suas chaves de criptografia possam ser acessadas pela sua conta do Azure Cosmos DB. A política de acesso é implementada concedendo acesso a uma identidade específica do Microsoft Entra. Há suporte para dois tipos de identidades:

A identidade de primeira parte do Azure Cosmos DB pode ser usada para conceder acesso ao serviço Azure Cosmos DB.
A identidade gerenciada da sua conta do Azure Cosmos DB pode ser usada para conceder acesso à sua conta especificamente.

Você pode usar modelos ARM para atribuir uma identidade gerenciada a uma política de acesso.

Como uma identidade gerenciada atribuída ao sistema só pode ser recuperada após a criação de sua conta, você ainda precisa criar sua conta inicialmente usando a identidade de primeira parte. Em seguida:

Se a identidade gerenciada atribuída ao sistema não tiver sido configurada durante a criação da conta, habilite uma identidade gerenciada atribuída ao sistema em sua conta e copie a principalId que foi atribuída.
Adicione as permissões correspondentes à sua conta do Azure Key Vault conforme descrito anteriormente. Em vez de usar a entidade de segurança do Cosmos DB, utilize o principalId copiado na etapa anterior em lugar da identidade própria do Azure Cosmos DB.
Atualize sua conta do Azure Cosmos DB para especificar que você deseja usar a identidade gerenciada atribuída ao sistema ao acessar suas chaves de criptografia no Cofre de Chaves do Azure.
```
{
  "type": " Microsoft.DocumentDB/databaseAccounts",
  "properties": {
    "defaultIdentity": "SystemAssignedIdentity",
    // ...
  },
  // ...
}
```
Opcionalmente, você pode remover a identidade de primeira parte do Azure Cosmos DB da sua política de acesso ao Cofre da Chave do Azure.

Você também pode seguir etapas semelhantes com uma identidade gerenciada atribuída pelo usuário.

Ao criar a nova política de acesso ou atribuição de função no seu Cofre de Chaves do Azure, use a Object ID da identidade gerida que pretende utilizar em vez da identidade de primeira parte do Azure Cosmos DB.

Ao criar sua conta do Azure Cosmos DB, você deve habilitar a identidade gerenciada atribuída pelo usuário e especificar que deseja usar essa identidade ao acessar suas chaves de criptografia no Cofre de Chaves do Azure.

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

Você pode usar a CLI do Azure para atribuir uma identidade gerenciada a uma política de acesso.

Se a identidade gerenciada atribuída ao sistema não tiver sido configurada durante a criação da conta, habilite uma identidade gerenciada atribuída ao sistema em sua conta e copie a principalId que foi atribuída.
Adicione as permissões correspondentes à sua conta do Azure Key Vault conforme descrito anteriormente. Em vez de usar a entidade de segurança do Cosmos DB, utilize o principalId copiado na etapa anterior em lugar da identidade própria do Azure Cosmos DB.

Atualize sua conta do Azure Cosmos DB para especificar que você deseja usar a identidade gerenciada atribuída ao sistema ao acessar suas chaves de criptografia no Cofre de Chaves do Azure.

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

Opcionalmente, você pode remover a identidade de primeira parte do Azure Cosmos DB da sua política de acesso ao Cofre da Chave do Azure.

Você também pode seguir etapas semelhantes com uma identidade gerenciada atribuída pelo usuário.

Ao criar a nova política de acesso ou atribuição de função no seu Cofre de Chaves do Azure, use a Object ID da identidade gerida que pretende utilizar em vez da identidade de primeira parte do Azure Cosmos DB.

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

Não disponível

Use chaves gerenciadas pelo cliente com backup contínuo

Você pode criar uma conta de backup contínuo usando a CLI do Azure ou um modelo ARM.

Atualmente, apenas a identidade gerenciada atribuída pelo usuário é suportada para a criação de contas de backup contínuo.

Depois que a conta for criada, você poderá atualizá-la para a identidade gerenciada atribuída ao sistema.

Como alternativa, os usuários também podem criar uma identidade do sistema com o modo de backup periódico primeiro e, em seguida, migrar a conta para o modo de backup contínuo. Para obter etapas detalhadas, consulte Migrar uma conta do Azure Cosmos DB do modo de backup periódico para o contínuo.

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

Quando você cria uma nova conta do Azure Cosmos DB por meio de um modelo ARM:

Passe a URL da chave do Azure Key Vault que copiaste anteriormente na propriedade keyVaultKeyUri no objeto properties.
Use 2021-11-15 ou posterior como a versão da API.

Importante

Você deve definir a locations propriedade explicitamente para que a conta seja criada com êxito com chaves gerenciadas pelo cliente, conforme mostrado no exemplo anterior.

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

Não disponível

Restaurar uma conta contínua configurada com identidade gerenciada

Uma identidade atribuída pelo usuário é necessária na solicitação de restauração porque a identidade gerenciada da conta de origem (identidades atribuídas pelo usuário e pelo sistema) não pode ser transferida automaticamente para a conta do banco de dados de destino.

CLI do Azure
Modelo do PowerShell / Azure Resource Manager / Portal do Azure

Use a CLI do Azure para restaurar uma conta contínua que já esteja configurada usando uma identidade gerenciada atribuída pelo sistema ou pelo usuário.

Crie uma nova identidade atribuída pelo usuário (ou use uma existente) para o processo de restauração.
Crie a nova política de acesso na sua conta do Azure Key Vault conforme descrito anteriormente. Use a ID do objeto da identidade gerenciada da etapa 1.

Acione a restauração usando a CLI do 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" \

Quando a restauração estiver concluída, a conta de destino (restaurada) terá a identidade atribuída pelo usuário. Se desejar, o usuário pode atualizar a conta para usar a identidade gerenciada atribuída pelo sistema.

Não disponível

Chaves gerenciadas pelo cliente e criptografia dupla

Os dados que você armazena em sua conta do Azure Cosmos DB ao usar chaves gerenciadas pelo cliente acabam sendo criptografados duas vezes:

Uma vez através da criptografia padrão realizada com chaves gerenciadas pela Microsoft.
Depois de passar pela criptografia extra realizada com chaves geridas pelo cliente.

A criptografia dupla só se aplica ao armazenamento transacional principal do Azure Cosmos DB. Alguns recursos envolvem a replicação interna de seus dados para um segundo nível de armazenamento onde a criptografia dupla não é fornecida, mesmo com chaves gerenciadas pelo cliente. Estas funcionalidades incluem:

Rotação de chaves

A rotação da chave gerenciada pelo cliente usada pela sua conta do Azure Cosmos DB pode ser feita de duas maneiras.

Crie uma nova versão da chave atualmente usada no Cofre de Chaves do Azure:

Troque a chave usada atualmente por outra atualizando o URI da chave na sua conta. No portal do Azure, vá para sua conta do Azure Cosmos DB e selecione Criptografia de Dados no menu à esquerda:

Captura de ecrã da opção Encriptação de Dados no menu de navegação de recursos.

Em seguida, substitua o URI da chave pela nova chave que deseja usar e selecione Salvar:

Veja como obter o mesmo resultado no 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

A chave ou versão de chave anterior pode ser desativada quando os logs de auditoria do Cofre de Chaves do Azure não mostrarem mais atividades do Azure Cosmos DB nessa chave ou versão de chave. Nenhuma atividade adicional deve ocorrer na chave anterior ou na versão da chave após 24 horas de rotação da chave.

A rotação automática de chaves no Cofre de Chaves do Azure é suportada, desde que a chave anterior não esteja desativada ou eliminada. Os sistemas internos precisam de algum tempo para acompanhar a nova versão da chave depois de validar que a conta não está em estado revogado ou em transição para habilitar chaves gerenciadas pelo cliente.

Processamento de erros

Se houver erros com chaves gerenciadas pelo cliente no Azure Cosmos DB, o Azure Cosmos DB retornará os detalhes do erro junto com um código de substatus HTTP na resposta. Você pode usar o código de substatus HTTP para depurar a causa raiz do problema. Para obter a lista de códigos de substatus HTTP suportados, consulte Códigos de status HTTP para o Azure Cosmos DB.

Perguntas mais frequentes

Aqui estão incluídas perguntas frequentes sobre como configurar chaves gerenciadas pelo cliente no Azure Cosmos DB.

Há mais cobranças para habilitar chaves gerenciadas pelo cliente?

Não, não há nenhum custo para ativar esse recurso.

Como as chaves gerenciadas pelo cliente influenciam o planejamento de capacidade?

As Unidades de Solicitação (RU) consumidas pelas operações do banco de dados têm um aumento para refletir o processamento extra necessário para executar a criptografia e a descriptografia de seus dados ao usar chaves gerenciadas pelo cliente. O consumo extra de RU pode levar a uma utilização ligeiramente maior da sua capacidade provisionada. Use esta tabela para orientação:

Tipo de operação	Solicitar aumento de unidade
Leituras pontuais (buscar itens por sua ID)	+ 5% por operação
Qualquer operação de gravação	+ 6% por operação \| Aproximadamente + 0,06 RU por propriedade indexada
Consultas, feed de alterações de leitura ou feed de conflitos	+ 15% por operação

Quais dados são criptografados com as chaves gerenciadas pelo cliente?

Todos os dados armazenados em sua conta do Azure Cosmos DB são criptografados com as chaves gerenciadas pelo cliente, exceto os seguintes metadados:

Os nomes de suas contas, bancos de dados e contêineres do Azure Cosmos DB
Os nomes dos procedimentos armazenados
Os caminhos de propriedade declarados em suas políticas de indexação
Os valores das chaves de partição dos seus contentores

As chaves gerenciadas pelo cliente são suportadas para contas existentes do Azure Cosmos DB?

Sim. Para saber mais, consulte Configurar chaves gerenciadas pelo cliente para sua conta existente do Azure Cosmos DB com o Azure Key Vault.

É possível usar chaves gerenciadas pelo cliente com o repositório analítico do Azure Cosmos DB?

Sim, o Azure Synapse Link suporta apenas a configuração de chaves gerenciadas pelo cliente usando a identidade gerenciada da sua conta do Azure Cosmos DB. Você deve usar a identidade gerenciada da sua conta do Azure Cosmos DB em sua política de acesso do Cofre da Chave do Azure antes de habilitar o Azure Synapse Link em sua conta. Para obter um guia de instruções sobre como habilitar a identidade gerenciada e usá-la em uma política de acesso, consulte acessar o Cofre da Chave do Azure a partir do Azure Cosmos DB usando uma identidade gerenciada.

Existe um plano para suportar uma granularidade mais detalhada do que as chaves no nível da conta?

Atualmente, não, mas as chaves no nível do contêiner estão sendo consideradas.

Como posso saber se as chaves gerenciadas pelo cliente estão habilitadas na minha conta do Azure Cosmos DB?

No portal do Azure, vá para sua conta do Azure Cosmos DB e observe a entrada de Criptografia de Dados no menu à esquerda. Se esta entrada existir, as chaves geridas pelo cliente estão ativadas na sua conta:

Captura de ecrã da opção Encriptação de dados no menu de navegação de recursos.

Você também pode buscar programaticamente os detalhes de sua conta do Azure Cosmos DB e procurar a presença da propriedade keyVaultKeyUri.

Como as chaves gerenciadas pelo cliente afetam os backups periódicos?

O Azure Cosmos DB faz backups regulares e automáticos dos dados armazenados em sua conta. Esta operação faz backup dos dados criptografados.

As seguintes condições são necessárias para restaurar com êxito um backup periódico:

A chave de criptografia que você usou no momento do backup é necessária e deve estar disponível no Cofre de Chaves do Azure. Essa condição requer que nenhuma revogação tenha sido feita e que a versão da chave que foi usada no momento do backup ainda esteja habilitada.
Se você usou uma identidade gerenciada atribuída ao sistema na política de acesso, conceda temporariamente acesso à identidade de primeira parte do Azure Cosmos DB antes de restaurar seus dados. Esse requisito existe porque uma identidade gerenciada atribuída ao sistema é específica de uma conta e não pode ser reutilizada na conta de destino. Assim que os dados estiverem totalmente restaurados na conta de destino, podes definir a configuração de identidade desejada e remover a identidade de primeira parte da política de acesso ao Key Vault.

Como as chaves gerenciadas pelo cliente afetam os backups contínuos?

O Azure Cosmos DB oferece a opção de configurar backups contínuos em sua conta. Com backups contínuos, pode restaurar os seus dados a qualquer ponto no tempo nos últimos 30 dias. Para usar backups contínuos em uma conta onde as chaves gerenciadas pelo cliente estão habilitadas, você deve usar uma identidade gerenciada atribuída pelo sistema ou pelo usuário na política de acesso ao Cofre de Chaves. Atualmente, as identidades primárias do Azure Cosmos DB não são suportadas em contas que usam backups contínuos.

Etapas de pré-requisito para contas habilitadas com chaves gerenciadas pelo cliente para atualizar a identidade atribuída pelo usuário.

Adicione uma identidade atribuída pelo usuário à conta do Cosmos DB e conceda permissões na política de acesso ao cofre de chaves.
Defina a identidade atribuída ao utilizador como padrão através da CLI do Azure ou do Azure Resource Manager (ARM).

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

As seguintes condições são necessárias para executar com êxito uma restauração num ponto no tempo:

O acesso à chave gerenciada pelo cliente deve estar disponível para a identidade padrão da conta. Se a chave tiver sido girada, o processo de rotação deve ser totalmente concluído ou a conta deve ter acesso às versões de chave antiga e nova.
Você deve garantir que a identidade gerenciada atribuída pelo usuário originalmente usada na conta de origem ainda esteja declarada na política de acesso ao Cofre da Chave.

Importante

Se você revogar a chave de criptografia antes de excluir sua conta, o backup da sua conta poderá perder os dados gravados até uma hora antes da revogação ser feita.

Como posso revogar uma chave de encriptação?

A revogação da chave é feita desativando a versão mais recente da chave:

Como alternativa, para revogar todas as chaves de uma instância do Cofre de Chaves do Azure, você pode excluir a política de acesso concedida à entidade de segurança do Azure Cosmos DB:

Quais operações estão disponíveis depois que uma chave gerenciada pelo cliente é revogada?

A exclusão de conta é a única operação possível quando a chave de criptografia foi revogada.

Atribua uma nova identidade gerenciada à conta de banco de dados restaurada para continuar acessando ou recuperando o acesso à conta de banco de dados

A identidade atribuída pelo usuário está vinculada a uma conta especificada do Cosmos DB, sempre que atribuímos uma identidade atribuída pelo usuário a uma conta, o ARM encaminha a solicitação para identidades de serviço gerenciado para fazer essa conexão. Atualmente, transferimos informações de identidade do usuário da conta do banco de dados de origem para a conta do banco de dados de destino durante a restauração (para restauração de backup contínuo e periódico) da CMK + identidade atribuída pelo usuário,

Os metadados de identidade são vinculados à conta do banco de dados de origem e o fluxo de trabalho de restauração não redefine o escopo da identidade para a conta do banco de dados de destino. Isso faz com que as contas de banco de dados restauradas fiquem em mau estado e fiquem inacessíveis depois que a conta de origem for excluída e o tempo de renovação da identidade expirar.

Etapas para atribuir uma nova identidade gerenciada:

Próximo passo

Encriptação de dados no Azure Cosmos DB

Partilhar via

Configurar chaves gerenciadas pelo cliente para sua conta do Azure Cosmos DB com o Azure Key Vault

Pré-requisitos

Registrar o provedor de recursos do Azure Cosmos DB

Configurar sua instância do Azure Key Vault

Escolha o modelo de segurança preferido

Adicionar uma política de acesso

Adicionar funções de controle de acesso baseadas em função

Validar se as funções estão definidas corretamente

Gerar uma chave no Azure Key Vault

Criar uma nova conta do Azure Cosmos DB

Usando uma identidade gerenciada na política de acesso do Cofre da Chave do Azure

Use chaves gerenciadas pelo cliente com backup contínuo

Restaurar uma conta contínua configurada com identidade gerenciada

Chaves gerenciadas pelo cliente e criptografia dupla

Rotação de chaves

Processamento de erros

Perguntas mais frequentes

Há mais cobranças para habilitar chaves gerenciadas pelo cliente?

Como as chaves gerenciadas pelo cliente influenciam o planejamento de capacidade?

Quais dados são criptografados com as chaves gerenciadas pelo cliente?

As chaves gerenciadas pelo cliente são suportadas para contas existentes do Azure Cosmos DB?

É possível usar chaves gerenciadas pelo cliente com o repositório analítico do Azure Cosmos DB?

Existe um plano para suportar uma granularidade mais detalhada do que as chaves no nível da conta?

Como posso saber se as chaves gerenciadas pelo cliente estão habilitadas na minha conta do Azure Cosmos DB?

Como as chaves gerenciadas pelo cliente afetam os backups periódicos?

Como as chaves gerenciadas pelo cliente afetam os backups contínuos?

Como posso revogar uma chave de encriptação?

Quais operações estão disponíveis depois que uma chave gerenciada pelo cliente é revogada?

Atribua uma nova identidade gerenciada à conta de banco de dados restaurada para continuar acessando ou recuperando o acesso à conta de banco de dados

Próximo passo

Comentários

Recursos adicionais