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

Artigo
08/15/2024

APLICA-SE AO: NoSQL MongoDB Cassandra Gremlin Table

Os dados armazenados em sua conta do Azure Cosmos DB são criptografados de forma automática e direta, com as chaves gerenciadas pela Microsoft (chaves gerenciadas pelo serviço). Você pode optar por adicionar uma segunda camada de criptografia com chaves gerenciadas por você (CMK, chaves gerenciadas pelo cliente).

Diagrama das camadas de criptografia em relação aos dados do cliente.

Você deve armazenar chaves gerenciadas pelo cliente no Azure Key Vault e fornecer uma chave para cada conta do Azure Cosmos DB que esteja habilitada com chaves gerenciadas pelo cliente. Essa chave é usada para criptografar todos os dados armazenados nessa conta.

Observação

Se você quiser habilitar chaves gerenciadas pelo cliente nas contas existentes do Azure Cosmos DB, veja o link aqui para obter mais detalhes

Aviso

Os nomes de campo a seguir estão reservados nas tabelas da API do 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 estiverem habilitadas, apenas os nomes de campo que começam com __sys_ serão reservados.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

Registrar-se no 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 primeira etapa.

Entre no portal do Azure, acesse sua assinatura do Azure e selecione Provedores de recursos na guia configurações:
Pesquise o provedor de recursos do 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

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

O uso de chaves gerenciadas pelo cliente com Azure Cosmos DB exige que você defina duas propriedades na instância do Azure Key Vault que você planeja usar para hospedar suas chaves de criptografia: Exclusão reversível e Proteção de limpeza.

Se você criar uma nova instância do Azure Key Vault, habilite essas propriedades durante a criação:
Se estiver usando uma instância existente do Azure Key Vault, você poderá verificar se essas propriedades estão habilitadas examinando a seção Propriedades no portal do Azure. Se qualquer uma dessas propriedades não estiver habilitada, consulte as seções “Habilitar a exclusão reversível” e “Habilitar a proteção de limpeza” em um dos seguintes artigos:
- Como usar a exclusão reversível com o PowerShell
- Como usar a exclusão reversível com a CLI do Azure

Escolhendo o modelo de segurança preferencial

Depois que a proteção contra limpar e a exclusão temporária tiverem sido habilitadas, na guia Política de acesso, você poderá escolher seu modelo de permissão preferencial a ser usado. As políticas de acesso são definidas por padrão, mas também há suporte para o controle de acesso baseado em função do Azure.

As permissões necessárias devem ser concedidas para permitir que o Cosmos DB use sua chave de criptografia. Essa etapa varia dependendo se o Azure Key Vault está usando políticas de acesso ou controle de acesso baseado em função.

Observação

É importante observar que apenas um modelo de segurança pode estar ativo por vez, portanto, não é necessário propagar o controle de acesso baseado em função 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á até a instância do Azure Key Vault que você planeja usar para hospedar suas chaves de criptografia. Selecione Políticas de acesso no menu à esquerda:
Selecione + Adicionar política de acesso.
No menu suspenso Permissões de chave, selecione as permissões Obter, Desencapsular chave e Encapsular chave:
Em Selecionar entidade de segurança, selecionar Nenhuma selecionada.
Pesquise a entidade de segurança do Azure Cosmos DB e a selecione. (Para facilitar a localização, você também pode pesquisar pela ID do aplicativo: 00001111-aaaa-2222-bbbb-3333cccc4444 para qualquer região do Azure, exceto regiões do Azure Governamental em que a ID do aplicativo é 11112222-bbbb-3333-cccc-4444dddd5555).

Dica

Isso registra a identidade primária do Azure Cosmos DB na política de acesso do Azure Key Vault. Se a entidade de segurança do Azure Cosmos DB não estiver na lista, talvez seja necessário registrar novamente o provedor de recursos Microsoft.DocumentDB.
Escolha Selecionar na parte inferior da tela.
Selecione Adicionar para adicionar a nova política de acesso.
Selecione Salvar na instância do Key Vault para salvar todas as alterações.

Adição de funções do controle de acesso baseado em função

No portal do Azure, vá até a instância do Azure Key Vault que você planeja usar para hospedar suas chaves de criptografia. Selecione Controle de acesso (IAM) no menu à esquerda e, em seguida, Conceder acesso a esse recurso.
Pesquise a função "Administrador do Key Vault" e atribua a si mesmo. Essa atribuição é feita pesquisando primeiro o nome da função na lista e, em seguida, clicando na guia "Membros". Na guia, selecione a opção "Usuário, grupo ou entidade de serviço" no rádio e procure sua conta do Azure. Depois que a conta tiver sido selecionada, a função poderá ser atribuída.
Em seguida, as permissões necessárias devem ser atribuídas à entidade de segurança do Cosmos DB. Portanto, como a última atribuição de função, acesse a página de atribuição, mas desta vez procure a função "Usuário do Serviço de Criptografia do Key Vault" e, na guia membros, procure a entidade de segurança do Cosmos DB. Para localizar a entidade de segurança, procure a entidade de segurança do Azure Cosmos DB e selecione-a.

Importante

Na região do Azure Governamental, a ID do aplicativo é 11112222-bbbb-3333-cccc-4444dddd5555.
Selecione Examinar + atribuir e a função será atribuída ao Cosmos DB.

Validar se as funções foram definidas corretamente

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

Depois que as funções tiverem sido atribuídas, selecione "Exibir acesso a esse recurso" na página Controle de Acesso IAM para verificar se tudo foi definido corretamente.
Na página, defina o escopo como "este recurso" e verifique se você tem a função Administrador do Key Vault e se a entidade de segurança do Cosmos DB tem a função Usuário de Criptografia do Key Vault.

Gerar uma chave no Azure Key Vault

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

No portal do Azure, vá até a instância do Azure Key Vault que você planeja usar para hospedar suas chaves de criptografia. Em seguida, selecione Chaves no menu à esquerda:
Selecione Gerar/Importar, forneça um nome para a nova chave e selecione um tamanho de chave RSA. Recomendamos um mínimo de 3072 para maior segurança. Em seguida, selecione Criar:
Dica

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, veja gerenciar Azure Key Vault 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 conta do Azure Cosmos DB

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

Quando 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 URI/identificador de chave da chave do Azure Key Vault que você copiou da etapa anterior:

Quando criar uma nova conta do Azure Cosmos DB com o PowerShell:

Passe o URI da chave do Azure Key Vault copiada anteriormente sob a propriedade keyVaultKeyUri em Propertyobject.
Use 2019-12-12 ou posterior como a versão da API.

Importante

Você deve definir a propriedade locations explicitamente para que a conta seja criada com êxito com as 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 tiver sido criada, você poderá verificar se as chaves gerenciadas pelo cliente foram habilitadas buscando o URI da chave do 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

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

Passe o URI da chave do Azure Key Vault que você copiou anteriormente sob a propriedade keyVaultKeyUri no objeto propriedades.
Use 2019-12-12 ou posterior como a versão da API.

Importante

Você deve definir a propriedade locations explicitamente para que a conta seja criada com êxito com as 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 criar uma nova conta do Azure Cosmos DB por meio da CLI do Azure, passe o URI da chave do Azure Key Vault que você copiou anteriormente no parâmetro --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

Depois que a conta tiver sido criada, você poderá verificar se as chaves gerenciadas pelo cliente foram habilitadas buscando o URI da chave do Azure Key Vault:

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

Importante

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

Uso da identidade gerenciada na política de acesso do Azure Key Vault

Essa política de acesso garante que as chaves de criptografia possam ser acessadas pela conta do Azure Cosmos DB. A política de acesso é implementada concedendo acesso a uma identidade específica do Microsoft Entra. Dois tipos de identidades são compatíveis:

A identidade primária do Azure Cosmos DB pode ser usada para conceder acesso ao serviço do Azure Cosmos DB.
A identidade gerenciada da conta do Azure Cosmos DB pode ser usada para conceder acesso especificamente à conta.

Você pode usar modelos do 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 da conta, você precisa criar inicialmente sua conta usando a identidade primária. Em seguida:

Se a identidade gerenciada atribuída pelo sistema não foi configurada durante a criação da conta, habilite uma identidade gerenciada atribuída pelo sistema em sua conta e copie o principalId que foi atribuído.
Adicione as permissões de correspondente à sua conta do Azure Key Vault, conforme descrito anteriormente. Em vez de usar a entidade de segurança do Cosmos DB, use o principalId copiado na etapa anterior em vez da identidade de terceiros 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 Azure Key Vault.
```
{
  "type": " Microsoft.DocumentDB/databaseAccounts",
  "properties": {
    "defaultIdentity": "SystemAssignedIdentity",
    // ...
  },
  // ...
}
```
Opcionalmente, você pode remover a identidade primária do Azure Cosmos DB da sua política de acesso do Azure Key Vault.

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

Ao criar a política de acesso ou atribuição de função em sua conta do Azure Key Vault, use o Object ID da identidade gerenciada que você deseja usar em vez da identidade de primeira parte do banco de dados 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 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>"
    // ...
  }
}

Você pode usar a CLI do Azure 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 da conta, você precisa criar inicialmente sua conta usando a identidade primária. Em seguida:

Se a identidade gerenciada atribuída pelo sistema não foi configurada durante a criação da conta, habilite uma identidade gerenciada atribuída pelo sistema em sua conta e copie o principalId que foi atribuído.
Adicione as permissões de correspondente à sua conta do Azure Key Vault, conforme descrito anteriormente. Em vez de usar a entidade de segurança do Cosmos DB, use o principalId copiado na etapa anterior em vez da identidade de terceiros 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 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"

Opcionalmente, você pode remover a identidade primária do Azure Cosmos DB da sua política de acesso do Azure Key Vault.

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

Ao criar a política de acesso ou atribuição de função em sua conta do Azure Key Vault, use o Object ID da identidade gerenciada que você deseja usar em vez da identidade de primeira parte do banco de dados 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

Usar chaves gerenciadas pelo cliente com backup contínuo

É possível criar uma conta de backup contínuo usando a CLI do Azure ou um modelo do Azure Resource Manager.

Atualmente, somente a identidade gerenciada atribuída pelo usuário tem suporte para a criação de contas de backup contínuas.

Depois que a conta tiver sido criada, você poderá atualizar a identidade para a identidade gerenciada atribuída pelo sistema.

Como alternativa, o usuário também pode criar uma identidade do sistema com o modo de backup periódico primeiro e migrar a conta para o modo de backup contínuo usando as instruções descritas em 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 de Azure Resource Manager:

Passe o URI da chave do Azure Key Vault que você copiou anteriormente sob a propriedade keyVaultKeyUri no objeto propriedades.
Use 15-11-2021 ou posterior como a versão da API.

Importante

Você deve definir a propriedade locations explicitamente para que a conta seja criada com êxito com as 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 a 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 atribuídas pelo sistema) não pode ser transferida automaticamente para a conta de banco de dados de destino.

CLI do Azure
PowerShell / modelo do Azure Resource Manager / portal do Azure

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

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

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

Depois que a restauração for concluída, a conta de destino (restaurada) terá a identidade atribuída pelo usuário. Se desejado, o usuário poderá 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 armazenados na conta do Azure Cosmos DB ao se usar chaves gerenciadas pelo cliente acabam sendo criptografados duas vezes:

Uma vez por meio da criptografia padrão executada com chaves gerenciadas pela Microsoft.
Uma vez por meio da criptografia extra executada com chaves gerenciadas pelo cliente.

A criptografia dupla só se aplica ao principal armazenamento transacional do Azure Cosmos DB. Alguns recursos envolvem a replicação interna dos dados para uma segunda camada de armazenamento em que a criptografia dupla não é fornecida, mesmo com chaves gerenciadas pelo cliente. Esses recursos incluem:

Alteração de chaves

O revezamento 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 usada atualmente no Azure Key Vault:

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

Captura de tela da opção Criptografia de Dados no menu de navegação do recurso.

Substitua o URI da chave pela nova chave que você deseja usar e selecione Salvar:

Veja como obter o mesmo resultado usando 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 a versão da chave anterior pode ser desabilitada após os logs de auditoria do Azure Key Vault não mostrarem mais a atividade do Azure Cosmos DB nessa chave ou versão da chave. Não ocorrerá nenhuma atividade adicional na chave anterior ou na versão da chave após 24 horas de rotação de chaves.

Há suporte para rotação automática de chaves no Azure Key Vault desde que a chave anterior não esteja desabilitada ou excluída. 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.

Tratamento de erros

Se houver qualquer erro com as 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. Use esse código de substatus HTTP para depurar a causa raiz do problema. Consulte o artigo Códigos de status HTTP para Azure Cosmos DB para obter a lista dos códigos de substatus HTTP com suporte.

Perguntas frequentes

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

Há mais encargos para habilitar chaves gerenciadas pelo cliente?

Não, não há encargos para habilitar esse recurso.

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

As Unidades de Solicitação consumidas por suas operações de banco de dados sofrem um aumento que reflete o processamento extra necessário para executar a criptografia e a descriptografia dos seus dados ao usar chaves gerenciadas pelo cliente. Esse consumo extra de RU pode levar a uma utilização um pouco mais alta de sua capacidade provisionada. Use essa tabela para obter diretrizes:

Tipo de operação	Aumento da Unidade de Solicitação
Leituras de ponto (buscando 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, leitura de feed de alterações 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 das suas contas, bancos de dados e contêineres do Azure Cosmos DB
Os nomes dos seus procedimentos armazenados
Os caminhos de propriedade declarados em suas políticas de indexação
Os valores das chaves de partição dos seus contêineres

As chaves gerenciadas pelo cliente têm suporte para contas existentes do Azure Cosmos DB?

Sim. Você pode consultar Como configurar chaves gerenciadas pelo cliente para suas contas existentes do Azure Cosmos DB

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

Sim, o Link do Azure Synapse só dá suporte à 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 Azure Key Vault antes de habilitar o Link do Azure Synapse 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 Azure Key Vault do Azure Cosmos DB usando uma identidade gerenciada.

Há um plano para dar suporte uma granularidade mais refinada do que as chaves de nível de conta?

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

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

Na portal do Azure, acesse sua conta do Azure Cosmos DB e veja a entrada da Criptografia de Dados no menu à esquerda. Se essa entrada existir, as chaves gerenciadas pelo cliente estão habilitadas em sua conta:

Captura de tela da opção Criptografia de dados no menu de navegação do recurso.

Você pode buscar via programa os detalhes da sua conta do Azure Cosmos DB e verificar a presença da propriedade keyVaultKeyUri.

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

O Azure Cosmos DB realiza 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 um backup periódico com êxito:

A chave de criptografia que você usou no momento do backup é necessária e deve estar disponível no Azure Key Vault. Essa condição demanda que nenhuma revogação tenha sido feita e a versão da chave que foi usada no momento do backup ainda esteja habilitada.
Se você usou uma identidade gerenciada atribuída pelo sistema na política de acesso, conceda temporariamente acesso à identidade primária do Azure Cosmos DB antes de restaurar seus dados. Este requerimento existe porque uma identidade gerenciada atribuída pelo sistema é específica de uma conta e não pode ser reutilizada na conta de destino. Depois que os dados são totalmente restaurados para a conta de destino, é possível definir sua configuração de identidade desejada e remover a identidade de primeira parte da política de acesso do 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 o backup contínuo, você pode restaurar seus dados para qualquer ponto no tempo nos últimos 30 dias. Para usar backups contínuos em uma conta em que as chaves gerenciadas pelo cliente estão ativadas, você deve usar uma identidade gerenciada atribuída pelo sistema ou pelo usuário na política de acesso do Key Vault. Atualmente, as identidades primárias do Azure Cosmos DB não têm suporte nas contas que usam backups contínuos.

Etapas de pré-requisito para contas habilitadas para Chaves Gerenciadas pelo Cliente atualizarem 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 do cofre de chaves.
Defina a identidade atribuída pelo usuário como padrão por meio da CLI do Azure ou do 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 pontual:

A chave de criptografia que você usou no momento do backup é necessária e deve estar disponível no Azure Key Vault. Esse requerimento significa que nenhuma revogação foi feita e a versão da chave que foi usada no momento do backup ainda estará habilitada.
Você deve garantir que a identidade gerenciada atribuída pelo usuário originalmente usada na conta de origem ainda seja declarada na política de acesso do Key Vault.

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 fazer para revogar uma chave de criptografia?

A revogação de uma chave é feita desabilitando a versão mais recente da chave:

Como alternativa, para revogar todas as chaves de uma instância do Azure Key Vault, 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 única operação possível quando a chave de criptografia é revogada é a exclusão da conta.

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

A Identidade atribuída pelo usuário está vinculada a uma conta do Cosmos DB especificada, /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 gerenciadas para fazer essa conexão. Atualmente, carregamos informações de identidade do usuário da conta de banco de dados de origem para a conta de banco de dados de destino durante a restauração (para restauração de backup contínua e periódica) do CMK + Identidade atribuída pelo usuário,

Uma vez que os metadados de identidade estão associados à conta de banco de dados de origem e o fluxo de trabalho de restauração não define novamente a identidade para a conta de banco de dados de destino. Isso fará com que as contas de banco de dados restauradas estejam em um estado inválido e se tornem 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óximas etapas

Saiba mais sobre a criptografia de dados no Azure Cosmos DB.

Compartilhar via

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

Pré-requisitos

Registrar-se no provedor de recursos do Azure Cosmos DB

Configurar sua instância do Azure Key Vault

Escolhendo o modelo de segurança preferencial

Adicionar uma política de acesso

Adição de funções do controle de acesso baseado em função

Validar se as funções foram definidas corretamente

Gerar uma chave no Azure Key Vault

Criar uma conta do Azure Cosmos DB

Uso da identidade gerenciada na política de acesso do Azure Key Vault

Usar chaves gerenciadas pelo cliente com backup contínuo

Restaurar uma conta contínua configurada com a identidade gerenciada

Chaves gerenciadas pelo cliente e criptografia dupla

Alteração de chaves

Tratamento de erros

Perguntas frequentes

Há mais encargos 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 têm suporte para contas existentes do Azure Cosmos DB?

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

Há um plano para dar suporte uma granularidade mais refinada do que as chaves de nível de conta?

Como 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 fazer para revogar uma chave de criptografia?

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

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

Próximas etapas

Comentários

Recursos adicionais