Configuración de claves administradas por el cliente para una cuenta de Azure Cosmos con Azure Key Vault
SE APLICA A: 
SQL API Cassandra API Gremlin API Table API Azure Cosmos DB API para MongoDB
Los datos almacenados en su cuenta de Azure Cosmos se cifran de forma automática y sin problemas con claves administradas por Microsoft (claves administradas por el servicio). También puede optar por agregar una segunda capa de cifrado con las claves administradas (claves administradas por el cliente o CMK).
Debe almacenar las claves administradas por el cliente en Azure Key Vault y proporcionar una clave para cada cuenta de Azure Cosmos que tenga habilitadas las claves administradas por el cliente. Esta clave se usa para cifrar todos los datos almacenados en esa cuenta.
Nota:
Actualmente, las claves administradas por el cliente solo están disponibles para las nuevas cuentas de Azure Cosmos. Debe configurarlas durante la creación de la cuenta.
Registro del proveedor de recursos de Azure Cosmos DB para su suscripción a Azure
Inicie sesión en Azure Portal, vaya a la suscripción de Azure y seleccione Proveedores de recursos en la pestaña Configuración:
Busque el proveedor de recursos Microsoft.DocumentDB. Compruebe si el proveedor de recursos ya está marcado como registrado. Si no es así, elija el proveedor de recursos y seleccione Registrar:
Configuración de la instancia de Azure Key Vault
Importante
Es necesario poder acceder a la instancia de Azure Key Vault a través del acceso a la red pública o permitir que los servicios de Microsoft de confianza omitan su firewall. Una instancia a la que se pueda acceder exclusivamente a través de puntos de conexión privados no se puede usar para hospedar las claves administradas por el cliente.
El uso de claves administradas por el cliente con Azure Cosmos DB requiere que establezca dos propiedades en la instancia de Azure Key Vault que planea usar para hospedar las claves de cifrado: Eliminación temporal y Protección de purga.
Si crea una nueva instancia de Azure Key Vault, habilite estas propiedades durante la creación:
Si usa una instancia de Azure Key Vault existente y desea verificar si estas propiedades estén habilitadas, puede consultar la sección Propiedades en Azure Portal. Si alguna de estas propiedades no está habilitada, consulte las secciones "Habilitar la eliminación temporal" y "Habilitación de la protección de purgas" en cualquiera de los siguientes artículos:
Adición de una directiva de acceso a la instancia de Azure Key Vault
En Azure Portal, vaya a la instancia de Azure Key Vault que planea usar para hospedar las claves de cifrado. Seleccione Directivas de acceso en el menú izquierdo:
Seleccione + Agregar directiva de acceso.
En el menú desplegable Permisos de claves, seleccione los permisos Obtener, Desencapsular clave y Encapsular clave:
En Seleccionar entidad de seguridad, seleccione Ninguna seleccionada.
Busque la entidad de seguridad de Azure Cosmos DB y selecciónela (para que sea más fácil de encontrar, también puede buscar por el identificador de la aplicación,
a232010e-820c-4083-83bb-3ace5fc29d0b, para cualquier región de Azure, excepto las regiones de Azure Government donde dicho identificador es57506a73-e302-42a9-b869-6f12d9ec29e9). Si la entidad de seguridad Azure Cosmos DB no está en la lista, es posible que tenga que volver a registrar el proveedor de recursos Microsoft.DocumentDB como se describe en la sección Registro del proveedor de recursos de este artículo.Nota:
De este modo, se registra la identidad de primera entidad de Azure Cosmos DB en la directiva de acceso de Azure Key Vault. Para reemplazar la identidad de primera entidad en función de su identidad administrada de la cuenta de Azure Cosmos DB, consulte uso de una identidad administrada en la directiva de acceso de Azure Key Vault.
Elija Seleccionar en la parte inferior.
Seleccione Agregar para agregar la nueva directiva de acceso.
Seleccione Guardar en la instancia de Key Vault para guardar todos los cambios.
Generación de una clave en Azure Key Vault
En Azure Portal, vaya a la instancia de Azure Key Vault que planea usar para hospedar las claves de cifrado. A continuación, seleccione Claves en el menú izquierdo:
Seleccione Generar/Importar, proporcione un nombre para la nueva clave y seleccione un tamaño de clave RSA. Para mejorar la seguridad, se recomienda un mínimo de 3072. A continuación, seleccione Crear:
Una vez creada la clave, seleccione la clave que se acaba de crear y, a continuación, su versión actual.
Copie el Identificador de clave de la clave, excepto la parte que se encuentra después de la última barra diagonal:
Creación de una cuenta de Azure Cosmos
Uso de Azure Portal
Al crear una nueva cuenta de Azure Cosmos DB desde Azure Portal, elija Clave administrada por el cliente en el paso Cifrado. En el campo URI de clave, pegue el URI o identificador de clave de la clave de Azure Key Vault que copió del paso anterior:
Uso de Azure PowerShell
Al crear una nueva cuenta de Azure Cosmos DB mediante PowerShell:
Pase el identificador URI de la clave de Azure Key Vault que copió anteriormente de la propiedad keyVaultKeyUri en PropertyObject.
Use 2019-12-12 o posterior como versión de la API.
Importante
Debe establecer la propiedad locations de manera explícita para que la cuenta se cree correctamente con claves administradas por el 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
Una vez que cree la cuenta, puede verificar que las claves administradas por el cliente se hayan habilitado mediante la captura del URI de la clave de Azure Key Vault:
Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
-ResourceType "Microsoft.DocumentDb/databaseAccounts" `
| Select-Object -ExpandProperty Properties `
| Select-Object -ExpandProperty keyVaultKeyUri
Uso de una plantilla de Azure Resource Manager
Al crear una nueva cuenta de Azure Cosmos con una plantilla de Azure Resource Manager:
Pase el URI de la clave de Azure Key Vault que copió anteriormente en la propiedad keyVaultKeyUri en el objeto properties.
Use 2019-12-12 o posterior como versión de la API.
Importante
Debe establecer la propiedad locations de manera explícita para que la cuenta se cree correctamente con claves administradas por el 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')]"
}
}
]
}
Implemente la plantilla con el siguiente script de 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
Uso de la CLI de Azure
Al crear una nueva cuenta de Azure Cosmos a través de la CLI de Azure, pase el URI de la clave de Azure Key Vault que copió anteriormente en el 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
Una vez que cree la cuenta, puede verificar que las claves administradas por el cliente se hayan habilitado mediante la captura del URI de la clave de Azure Key Vault:
az cosmosdb show \
-n $accountName \
-g $resourceGroupName \
--query keyVaultKeyUri
Uso de una identidad administrada en la directiva de acceso de Azure Key Vault
Esta directiva de acceso garantiza que la cuenta de Azure Cosmos DB pueda acceder a sus claves de cifrado. Para implementar la directiva de acceso, se concede acceso a una identidad específica de Azure Active Directory (AD). Se admiten dos tipos de identidades:
- La identidad de primera entidad de Azure Cosmos DB se puede usar para conceder acceso al servicio Azure Cosmos DB.
- La identidad administrada de la cuenta de Azure Cosmos DB se puede usar para conceder acceso a su cuenta específicamente.
Uso de una identidad administrada asignada por el sistema
Dado que una identidad administrada asignada por el sistema solo se puede recuperar después de crear la cuenta, primero deberá crear la cuenta mediante la identidad de primera entidad, tal como se ha descrito anteriormente. A continuación:
Si la identidad administrada asignada por el sistema no se configuró durante la creación de la cuenta, habilite una identidad administrada asignada por el sistema en su cuenta y copie el valor de
principalIdque se asignó.Agregue una nueva directiva de acceso a su cuenta de Azure Key Vault como se describió anteriormente, pero utilice el valor de
principalIdque copió en el paso anterior en lugar de la identidad de primera entidad de Azure Cosmos DB.Actualice su cuenta de Azure Cosmos DB para especificar que desea usar la identidad administrada asignada por el sistema al acceder a las claves de cifrado en Azure Key Vault. Tiene dos opciones:
Especifique la propiedad en la plantilla de Azure Resource Manager de su cuenta:
{ "type": " Microsoft.DocumentDB/databaseAccounts", "properties": { "defaultIdentity": "SystemAssignedIdentity", // ... }, // ... }Actualice su cuenta con la CLI de Azure:
resourceGroupName='myResourceGroup' accountName='mycosmosaccount' az cosmosdb update --resource-group $resourceGroupName --name $accountName --default-identity "SystemAssignedIdentity"
De manera opcional, puede quitar la identidad de primera entidad de Azure Cosmos DB de la directiva de acceso de Azure Key Vault.
Uso de una identidad administrada asignada por el usuario
Al crear la nueva directiva de acceso en la cuenta de Azure Key Vault como se describió anteriormente, use el valor de
Object IDde la identidad administrada que desea usar en lugar de la identidad de primera entidad de Azure Cosmos DB.Al crear la cuenta de Azure Cosmos DB, debe habilitar la identidad administrada asignada por el usuario y especificar que quiere usar esta identidad al acceder a las claves de cifrado en Azure Key Vault. Entre las opciones se incluyen:
Uso de una plantilla de Azure Resource Manager:
{ "type": "Microsoft.DocumentDB/databaseAccounts", "identity": { "type": "UserAssigned", "userAssignedIdentities": { "<identity-resource-id>": {} } }, // ... "properties": { "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>" "keyVaultKeyUri": "<key-vault-key-uri>" // ... } }En la CLI de Azure:
resourceGroupName='myResourceGroup' accountName='mycosmosaccount' keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>' az cosmosdb create \ -n $accountName \ -g $resourceGroupName \ --key-uri $keyVaultKeyUri --assign-identity <identity-resource-id> --default-identity "UserAssignedIdentity=<identity-resource-id>"
Uso de CMK con copia de seguridad continua
Puede crear una cuenta de copia de seguridad continua mediante la CLI de Azure o una plantilla de Resource Manager.
Actualmente, solo se admite la identidad administrada asignada por el usuario para crear cuentas de copia de seguridad continua.
Para crear una cuenta de copia de seguridad continua mediante la CLI de Azure
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'
az cosmosdb create \
-n $accountName \
-g $resourceGroupName \
--key-uri $keyVaultKeyUri \
--locations regionName=<Location> \
--assign-identity <identity-resource-id> \
--default-identity "UserAssignedIdentity=<identity-resource-id>" \
--backup-policy-type Continuous
Para crear una cuenta de copia de seguridad continua mediante una plantilla de Azure Resource Manager
Al crear una nueva cuenta de Azure Cosmos con una plantilla de Azure Resource Manager:
- Pase el URI de la clave de Azure Key Vault que copió anteriormente en la propiedad keyVaultKeyUri en el objeto properties.
- Use 2021-11-15 o posterior como versión de la API.
Importante
Debe establecer la propiedad locations de manera explícita para que la cuenta se cree correctamente con claves administradas por el cliente tal y como se muestra en el ejemplo 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>"
// ...
}
}
Claves administradas por el cliente y cifrado doble
Los datos que almacena en la cuenta de Azure Cosmos DB cuando se usan claves administradas por el cliente se cifran dos veces:
- Una vez mediante el cifrado predeterminado aplicado con claves administradas por Microsoft.
- Una vez mediante el cifrado adicional aplicado con claves administradas por el cliente.
El cifrado doble solo se aplica al almacenamiento transaccional principal de Azure Cosmos DB. Algunas características implican la replicación interna de los datos en un segundo nivel de almacenamiento donde no se proporciona cifrado doble, incluso con las claves administradas por el cliente. Entre ellas se incluyen:
Rotación de claves
La rotación de la clave administrada por el cliente que usa la cuenta de Azure Cosmos se puede realizar de dos maneras.
Cree una nueva versión de la clave que se usa actualmente en Azure Key Vault:
Intercambie la clave que se usa en este momento con otra distinta mediante la actualización del URI de la clave en la cuenta. En Azure Portal, vaya a su cuenta de Azure Cosmos y seleccione Cifrado de datos en el menú de la izquierda:
A continuación, reemplace el URI de clave por la nueva clave que desee usar y seleccione Guardar:
Aquí se muestra cómo lograr el mismo resultado en 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
La versión de la clave o la clave anterior pueden deshabilitarse después de que los registros de auditoría de Azure Key Vault no muestren actividad de Azure Cosmos DB en esa clave o versión. No debe haber más actividad en la versión de clave o clave anterior transcurridas 24 horas desde la rotación de claves.
Control de errores
Si hay algún error con las claves administradas por el cliente en Azure Cosmos DB, este servicio devuelve los detalles del error junto con un código de subestado HTTP en la respuesta. Puede usar este código de subestado HTTP para depurar la causa principal del problema. Consulte el artículo Códigos de estado HTTP para Azure Cosmos DB para obtener la lista de códigos de subestado HTTP admitidos.
Preguntas más frecuentes
¿Hay más cargos por habilitar las claves administradas por el cliente?
No, no hay ningún cargo por habilitar esta característica.
¿De qué manera las claves administradas por el cliente influyen en el planeamiento de la capacidad?
Las unidades de solicitud que consumen las operaciones de base de datos observan un aumento para reflejar el procesamiento adicional necesario para realizar el cifrado y el descifrado de los datos al usar claves administradas por el cliente. Este consumo de RU adicional puede dar lugar a un uso ligeramente mayor de la capacidad aprovisionada. Emplee la tabla siguiente como guía:
| Tipo de operación | Aumento de las Unidades de solicitud |
|---|---|
| Lecturas de punto (captura de elementos por su identificador) | + 5 % por operación |
| Cualquier operación de escritura | + 6 % por operación Aproximadamente + 0,06 RU por propiedad indexada |
| Consultas, lectura de la fuente de cambios o fuente de conflictos | + 15 % por operación |
¿Qué datos se cifran con las claves administradas por el cliente?
Todos los datos almacenados en la cuenta de Azure Cosmos se cifran con las claves administradas por el cliente, excepto los metadatos siguientes:
Los nombres de las cuentas, bases de datos y contenedores de Azure Cosmos DB
Los nombres de los procedimientos almacenados
Las rutas de acceso a las propiedades declaradas en las directivas de indexación
Los valores de la clave de partición de los contenedores
¿Son compatibles las claves administradas por el cliente con las cuentas existentes de Azure Cosmos?
Esta característica solo está disponible actualmente para las cuentas nuevas.
¿Es posible usar claves administradas por el cliente con el almacén analítico de Azure Cosmos DB?
Sí, Azure Synapse Link solamente admite la configuración de claves administradas por el cliente mediante la identidad administrada de la cuenta de Azure Cosmos DB. Debe usar la identidad administrada de la cuenta de Azure Cosmos DB en la directiva de acceso de Azure Key Vault antes de habilitar Azure Synapse Link en la cuenta. Para obtener una guía paso a paso sobre cómo habilitar la identidad administrada y cómo usarla en una directiva de acceso, consulte el acceso a Azure Key Vault desde Azure Cosmos DB con una identidad administrada.
¿Existe un plan para admitir una granularidad más fina que las claves de nivel de cuenta?
Actualmente, no. Sin embargo, se está analizando la posibilidad de incluir claves de nivel de contenedor.
¿Cómo se puede saber si las claves administradas por el cliente están habilitadas en mi cuenta de Azure Cosmos?
En Azure Portal, vaya a su cuenta de Azure Cosmos y observe la entrada de Cifrado de datos del menú de la izquierda. Si esta entrada existe, las claves administradas por el cliente estarán habilitadas en su cuenta:
También puede recuperar los detalles de la cuenta de Azure Cosmos mediante programación y buscar la presencia de la propiedad keyVaultKeyUri. Consulte anteriormente para conocer formas de hacerlo en PowerShell y mediante la CLI de Azure.
¿Cómo afectan las claves administradas por el cliente a las copias de seguridad periódicas?
Azure Cosmos DB realiza copias de seguridad periódicas y automáticas de los datos almacenados en su cuenta. Esta operación realiza una copia de seguridad de los datos cifrados.
Se necesitan las siguientes condiciones para restaurar correctamente una copia de seguridad periódica:
- La clave de cifrado que usó en el momento de la copia de seguridad es necesaria y debe estar disponible en Azure Key Vault. Esta condición requiere que no se haya realizado ninguna revocación y que la versión de la clave que se usó en el momento de la copia de seguridad aún esté habilitada.
- Si usó una identidad administrada asignada por el sistema en la directiva de acceso, conceda acceso a la identidad de primera persona de Azure Cosmos DB temporalmente antes de restaurar los datos. Este requisito existe porque una identidad administrada asignada por el sistema es específica de una cuenta y no se puede reutilizar en la cuenta de destino. Una vez que los datos se restablezcan completamente en la cuenta de destino, puede establecer la configuración de identidad que quiera y quitar la identidad de primera entidad de la directiva de acceso de Key Vault.
¿Cómo afectan las claves administradas por el cliente a las copias de seguridad continuas?
Azure Cosmos DB ofrece la opción de configurar copias de seguridad continuas en la cuenta. Con las copias de seguridad continuas, puede restaurar los datos a cualquier momento dado de los últimos 30 días. Para usar copias de seguridad continuas en una cuenta donde las claves administradas por el cliente están habilitadas, debe usar una identidad administrada asignada por el usuario en la directiva de acceso de Key Vault. Las identidades propias de Azure Cosmos DB o las identidades administradas asignadas por el sistema no se admiten actualmente en las cuentas que usan copias de seguridad continuas.
Las condiciones siguientes son necesarias para realizar correctamente una restauración a un momento dado:
- La clave de cifrado que usó en el momento de la copia de seguridad es necesaria y debe estar disponible en Azure Key Vault. Este requisito significa que no se ha realizado ninguna revocación y que la versión de la clave que se usó en el momento de la copia de seguridad aún está habilitada.
- Debe asegurarse de que la identidad administrada asignada por el usuario que se usó originalmente en la cuenta de origen todavía se declara en la directiva de acceso de Key Vault.
Importante
Si revoca la clave de cifrado antes de eliminar la cuenta, la copia de seguridad de la cuenta puede perder los datos escritos hasta una hora antes de que se realizara la revocación.
¿Cómo se revoca una clave de cifrado?
Para revocar una clave, se debe deshabilitar la versión más reciente de la clave:
Como alternativa, para revocar todas las claves de una instancia de Azure Key Vault, puede eliminar la directiva de acceso concedida a la entidad de seguridad de Azure Cosmos DB:
¿Qué operaciones hay disponibles después de la revocación de una clave administrada por el cliente?
La única operación posible cuando se ha revocado la clave de cifrado es la eliminación de la cuenta.
Pasos siguientes
- Más información sobre el cifrado de datos en Azure Cosmos DB.
- Obtenga información general sobre el acceso seguro a los datos en Cosmos DB.