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

APLICA-SE A: API do SQL API do Cassandra API do Gremlin API de Tabela API do Azure Cosmos DB para MongoDB

Os dados armazenados em sua conta do Azure Cosmos 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ê (chaves gerenciadas pelo cliente).

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 que esteja habilitada com chaves gerenciadas pelo cliente. Essa chave é usada para criptografar todos os dados armazenados nessa conta.

Observação

Atualmente, as chaves gerenciadas pelo cliente estão disponíveis apenas para novas contas do Azure Cosmos. Você deve configurá-las durante a criação da conta.

Registrar o provedor de recursos do Azure Cosmos DB para sua assinatura do Azure

  1. Entre no portal do Azure, acesse sua assinatura do Azure e selecione Provedores de recursos na guia configurações:

    Entrada de provedores de recursos no menu à esquerda

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

    Registrar o provedor de recursos do Microsoft.DocumentDB

Configurar sua instância do Azure Key Vault

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:

Habilitar a exclusão reversível e a proteção de limpeza para uma nova instância do Azure Key Vault

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:

Adicionar uma política de acesso à instância do Azure Key Vault

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

    Políticas de acesso no menu à esquerda

  2. Selecione + Adicionar política de acesso.

  3. No menu suspenso Permissões de chave, selecione as permissões Obter, Desencapsular chave e Encapsular chave:

    Selecionar as permissões certas

  4. Em Selecionar entidade de segurança, selecionar Nenhuma selecionada.

  5. 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 da entidade de segurança: a232010e-820c-4083-83bb-3ace5fc29d0b para qualquer região do Azure, exceto regiões do Azure Governamental em que a ID da entidade de segurança é 57506a73-e302-42a9-b869-6f12d9ec29e9. 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, conforme descrito na seção Registrar o provedor de recursos deste artigo.

    Observação

    Isso registra a identidade primária do Azure Cosmos DB na política de acesso do Azure Key Vault. Para substituir essa identidade primária pela identidade gerenciada da conta do Azure Cosmos DB, consulte Uso da identidade gerenciada na política de acesso do Azure Key Vault.

  6. Escolha Selecionar na parte inferior da tela.

    Selecionar a entidade de segurança do Azure Cosmos DB

  7. Selecione Adicionar para adicionar a nova política de acesso.

  8. Selecione Salvar na instância do Key Vault para salvar todas as alterações.

Gerar uma chave no Azure Key Vault

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

    Entrada para chaves no menu à esquerda

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

    Criar uma nova chave

  3. Depois que a chave for criada, selecione a chave recém-criada e, em seguida, sua versão atual.

  4. Copie o Identificador de chave da chave, exceto a parte após a última barra “/”:

    Copiar o identificador de chave da chave

Criar uma nova conta do Azure Cosmos

Usando o portal 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:

Definir os parâmetros da chave gerenciada pelo cliente no portal do Azure

Usar o PowerShell do Azure

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.

$resourceGroupName = "myResourceGroup"
$accountLocation = "West US 2"
$accountName = "mycosmosaccount"

$failoverLocations = @(
    @{ "locationName"="West US 2"; "failoverPriority"=0 }
)

$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$failoverLocations;
    "keyVaultKeyUri" = "https://<my-vault>.vault.azure.net/keys/<my-key>";
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2019-12-12" -ResourceGroupName $resourceGroupName `
    -Location $accountLocation -Name $accountName -PropertyObject $CosmosDBProperties

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:

Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    | Select-Object -ExpandProperty Properties `
    | Select-Object -ExpandProperty keyVaultKeyUri

Usando um modelo do Azure Resource Manager

Quando você cria uma nova conta do Azure Cosmos 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:

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$accountLocation = "West US 2"
$keyVaultKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-key>"

New-AzResourceGroupDeployment `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile "deploy.json" `
    -accountName $accountName `
    -location $accountLocation `
    -keyVaultKeyUri $keyVaultKeyUri

Usar a CLI do Azure

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

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='West US 2' failoverPriority=0 isZoneRedundant=False \
    --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 \
    -n $accountName \
    -g $resourceGroupName \
    --query keyVaultKeyUri

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. Isso é feito concedendo acesso a uma identidade específica do AD (Azure Active Directory). 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.

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, conforme descrito acima. Em seguida:

  1. Se isso não foi feito durante a criação da conta, habilite uma identidade gerenciada atribuída ao sistema em sua conta e copie o principalId que foi atribuído.

  2. Adicione uma nova política de acesso à sua conta do Azure Key Vault, conforme descrito acima, mas usando o principalId que você copiou na etapa anterior, em vez da identidade primária do Azure Cosmos DB.

  3. 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. Você pode fazer isso:

    • especificando essa propriedade no modelo do Azure Resource Manager da sua conta:

      {
          "type": " Microsoft.DocumentDB/databaseAccounts",
          "properties": {
              "defaultIdentity": "SystemAssignedIdentity",
              // ...
          },
          // ...
      }
      
    • atualizando sua conta com a CLI do Azure:

      resourceGroupName='myResourceGroup'
      accountName='mycosmosaccount'
      
      az cosmosdb update --resource-group $resourceGroupName --name $accountName --default-identity "SystemAssignedIdentity"
      
  4. Opcionalmente, você pode remover a identidade primária do Azure Cosmos DB da sua política de acesso do Azure Key Vault.

Alteração de chaves

O revezamento da chave gerenciada pelo cliente, usada pela sua conta do Azure Cosmos, pode ser feita de duas maneiras.

  • Crie uma nova versão da chave usada atualmente no Azure Key Vault:

    Criar uma nova versão da chave

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

    Entrada do menu de Criptografia de Dados

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

    Atualizar o URI da chave

    Veja como obter o mesmo resultado usando PowerShell:

    $resourceGroupName = "myResourceGroup"
    $accountName = "mycosmosaccount"
    $newKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-new-key>"
    
    $account = Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
        -ResourceType "Microsoft.DocumentDb/databaseAccounts"
    
    $account.Properties.keyVaultKeyUri = $newKeyUri
    
    $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.

Tratamento de erros

Ao usar chaves CMK (Chave Gerenciada pelo Cliente) no Azure Cosmos DB, se houver erros, 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 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

Há encargos adicionais para habilitar chaves gerenciadas pelo cliente?

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

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

Quando chaves gerenciadas pelo cliente são usadas, as Unidades de Solicitação consumidas por suas operações de banco de dados sofrem um aumento que reflete o processamento adicional necessário para executar a criptografia e a descriptografia dos seus dados. Isso pode levar a uma utilização um pouco mais alta de sua capacidade provisionada. Use a tabela abaixo como orientação:

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
aprox. + 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 são criptografados com as chaves gerenciadas pelo cliente, exceto os seguintes metadados:

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

Este recurso está atualmente disponível somente para novas contas.

É possível usar chaves gerenciadas pelo cliente em conjunto 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.

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?

Na portal do Azure, acesse sua conta do Azure Cosmos 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:

Entrada do menu de Criptografia de Dados

Você pode buscar via programa os detalhes da sua conta do Azure Cosmos e verificar a presença da propriedade keyVaultKeyUri. Consulte acima para saber as maneiras de como fazer isso no PowerShell e usando a CLI do Azure.

Como as chaves gerenciadas pelo cliente afetam um backup?

O Azure Cosmos DB realiza backups regulares e automáticos dos dados armazenados em sua conta. Esta operação faz backup dos dados criptografados. Para usar o backup restaurado, a chave de criptografia que você usou no momento do backup é necessária. Isso significa que nenhuma revogação foi feita e a versão da chave que foi usada no momento do backup ainda estará habilitada.

Como fazer para revogar uma chave de criptografia?

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

Desabilitar a versão de uma 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:

Excluir a política de acesso para a 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.

Próximas etapas