Tutorial: Almacenamiento y uso de credenciales de Azure Cosmos DB con Azure Key Vault

SE APLICA A: NoSQL MongoDB Cassandra Gremlin Table

Importante

Es recomendable acceder a las claves de Azure Cosmos DB para usar una identidad administrada asignada por el sistema. Si la solución de identidad administrada y la solución basada en certificados no satisfacen sus necesidades, use la solución Azure Key Vault como se indica en este artículo.

Si usa Azure Cosmos DB como base de datos, se conectará a bases de datos, contenedores y elementos mediante un SDK, el punto de conexión de la API y la clave principal o secundaria.

No es recomendable almacenar el URI del punto de conexión y las claves confidenciales de lectura y escritura directamente en el código de aplicación o el archivo de configuración. Idealmente, estos datos se leen de variables de entorno dentro del host. En Azure App Service, la configuración de la aplicación permite insertar credenciales del entorno de ejecución para la cuenta de Azure Cosmos DB sin necesidad de que los desarrolladores almacenen estas credenciales en forma de texto no cifrado poco seguro.

Azure Key Vault recorre en iteración este procedimiento recomendado y le permite almacenar estas credenciales de forma segura al mismo tiempo que proporciona a servicios como Azure App Service acceso administrado a las credenciales. Azure App Service leerá de forma segura las credenciales de Azure Key Vault e insertará esas credenciales en la aplicación en ejecución.

Con este procedimiento recomendado, los desarrolladores pueden almacenar las credenciales de herramientas como el emulador de Azure Cosmos DB o Prueba de Azure Cosmos DB gratis durante el desarrollo. Posteriormente, el equipo de operaciones puede asegurarse de que se inserte la configuración de producción correcta en el entorno de ejecución.

En este tutorial, aprenderá a:

• Creación de una instancia de Azure Key Vault
• Agregar credenciales de Azure Cosmos DB como secretos al almacén de claves
• Crear y registrar un recurso de Azure App Service y conceder permisos de "lectura de clave"
• Insertar secretos del almacén de claves en el recurso de App Service

Nota

En este tutorial y en la aplicación de ejemplo se usa una cuenta de Azure Cosmos DB for NoSQL. Puede realizar muchos de los mismos pasos con otras API.

Requisitos previos

• Una cuenta existente de Azure Cosmos DB for NoSQL.
  • Si tiene una suscripción de Azure, cree una nueva cuenta.
  • Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
  • Como alternativa, puede probar Azure Cosmos DB gratis antes de confirmarlo.
• Una cuenta de GitHub.

Antes de empezar, consulte Obtención de credenciales de Azure Cosmos DB

Antes de empezar, obtendrá las credenciales de la cuenta existente.

1. Vaya a la página Azure Portal para ver la cuenta existente de Azure Cosmos DB for NoSQL.

2. En la página de la cuenta de Azure Cosmos DB for NoSQL, seleccione la opción del menú de navegación Claves.

   

3. Registre los valores de los campos URI y CLAVE PRINCIPAL. Estos valores se usarán más adelante en el tutorial.

   

Creación de un recurso de Azure Key Vault

En primer lugar, cree un nuevo almacén de claves para almacenar la API para las credenciales de noSQL.

1. Inicie sesión en Azure Portal.

2. Seleccione Crear un recurso > Seguridad > Key Vault.

3. En la página Crear almacén de claves, escriba la información siguiente:

   Configuración	Descripción
   Suscripción	Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos.
   Grupos de recursos	Seleccione un grupo de recursos o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.
   Nombre del almacén de claves	Escriba un nombre único global para el almacén de claves.
   Región	Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.
   Plan de tarifa	Seleccione Estándar.

4. Deje las opciones restantes en sus valores predeterminados.

5. Seleccione Revisar + crear.

6. Revise la configuración que proporcione y, a continuación, seleccione Crear. La operación de creación de la cuenta tarda unos minutos. Antes de avanzar, espere a que la página del portal muestre Se completó la implementación.

Adición de claves de acceso de Azure Cosmos DB en Key Vault

Ahora, almacene las credenciales de Azure Cosmos DB como secretos en el almacén de claves.

1. Seleccione Ir al recurso para ir a la página de recursos de Azure Key Vault.

2. En la página de recursos de Azure Key Vault, seleccione la opción del menú de navegación Secretos.

3. Seleccione Generar o importar en el menú.

   

4. En la página Crear un secreto, escriba la información siguiente:

   Configuración	Descripción
   Opciones de carga	Manual
   Nombre	cosmos-endpoint
   Valor del secreto	Escriba el URI que copió anteriormente en este tutorial.

   

5. Seleccione Crear para crear el nuevo secreto de cosmos-endpoint.

6. Seleccione otra vez Generar o importar en el menú. En la página Crear un secreto, escriba la información siguiente:

   Configuración	Descripción
   Opciones de carga	Manual
   Nombre	cosmos-readwrite-key
   Valor del secreto	Escriba la CLAVE PRINCIPAL que copió anteriormente en este tutorial.

   

7. Seleccione Crear para crear el nuevo secreto cosmos-readwrite-key.

8. Una vez creados los secretos, podrá verlos en la lista de secretos de la página Secretos.

   

9. Seleccione cada clave, seleccione la versión más reciente y copie el identificador secreto. Usará el identificador de los secretos cosmos-endpoint y cosmos-readwrite-key más adelante en este tutorial.

   Sugerencia

   El identificador secreto estará en este formato https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version-id>. Por ejemplo, si el nombre del almacén de claves es msdocs-key-vault, el nombre de la clave es cosmos-readwrite-key y la versión es 83b995e36363d947999ac6cf487ae0e12e, el identificador secreto será https://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e.

   

Creación y registro de una aplicación web de Azure con Azure Key Vault

En esta sección, cree una nueva aplicación web de Azure, implemente una aplicación de ejemplo y, a continuación, registre la identidad administrada de la aplicación web con Azure Key Vault.

1. Cree un nuevo repositorio de GitHub mediante la plantilla cosmos-db-nosql-dotnet-sample-web-environment-variables.

2. En Azure Portal, seleccione Crear un recurso > Web > Aplicación web.

3. En la página Crear aplicación web, en la pestaña Información básica, escriba la información siguiente:

   Configuración	Descripción
   Suscripción	Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos.
   Grupos de recursos	Seleccione un grupo de recursos o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.
   Nombre	Escriba un nombre único global para la aplicación web.
   Publicar	Seleccione Código.
   Pila del entorno en tiempo de ejecución	Seleccione .NET 6 (LTS).
   Sistema operativo	Seleccione Windows.
   Región	Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.

4. Deje las opciones restantes en sus valores predeterminados.

5. Seleccione Siguiente: Implementación.

6. Especifique la siguiente información en la pestaña Implementación:

   Configuración	Descripción
   Implementación continua	Seleccione Habilitar.
   Cuenta de GitHub	Seleccione Autorizar. Siga las indicaciones de autorización de la cuenta de GitHub para conceder permiso a Azure para leer el repositorio de GitHub recién creado.
   Organización	Seleccione la organización para el nuevo repositorio de GitHub.
   Repositorio	Seleccione el nombre del nuevo repositorio de GitHub.
   Rama	Seleccione main (principal).

7. Seleccione Revisar + crear.

8. Revise la configuración que proporcione y, a continuación, seleccione Crear. La operación de creación de la cuenta tarda unos minutos. Antes de avanzar, espere a que la página del portal muestre Se completó la implementación.

9. Es posible que tenga que esperar unos minutos adicionales para que la aplicación web se implemente inicialmente en Web Apps. En la página de recursos de Azure Web Apps, seleccione Examinar para ver el estado predeterminado de la aplicación.

   

10. Seleccione la opción Identidad del menú de navegación.

11. En la página Identidad, seleccione Activado para la identidad administrada asignada por el sistema y, a continuación, seleccione Guardar.

    

Inserción de secretos de Azure Key Vault como configuración de la aplicación de Azure Web Apps

Por último, inserte los secretos almacenados en el almacén de claves como configuración de la aplicación en Web Apps. La configuración de la aplicación insertará, a su vez, las credenciales en la aplicación en el entorno de ejecución sin almacenar las credenciales como texto no cifrado.

1. Vuelva a la página del almacén de claves en Azure Portal. Seleccione Directivas de acceso en el menú de navegación.

2. En la página Directivas de acceso, seleccione Crear en el menú.

   

3. En la pestaña Permisos de la página Crear una directiva de acceso, seleccione la opción Obtener en la sección Permisos secretos. Seleccione Siguiente.

   

4. En la pestaña Entidad de seguridad, seleccione el nombre de la aplicación web que creó anteriormente en este tutorial. Seleccione Siguiente.

   

   Nota

   En esta captura de pantalla de ejemplo, la aplicación web se denomina msdocs-dotnet-web.

5. Seleccione Siguiente de nuevo para omitir la pestaña Aplicación. En la pestaña Revisar y crear, revise la configuración que ha proporcionado y seleccione Crear.

6. Vuelva a la página de la aplicación web en Azure Portal. Seleccione Configuración en el menú de navegación.

7. En la página Configuración, seleccione Nueva configuración de la aplicación. En el cuadro de diálogo Agregar o editar configuración de la aplicación, escriba la siguiente información:

   Configuración	Descripción
   Nombre	CREDENTIALS__ENDPOINT
   Clave	Obtenga el identificador del secreto cosmos-endpoint en el almacén de claves que creó anteriormente en este tutorial. Especifique el identificador con el formato siguiente: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

   Sugerencia

   Asegúrese de que la variable de entorno tenga un valor de subrayado doble (__) en lugar de un carácter de subrayado simple. El carácter de subrayado doble es un delimitador de clave compatible con .NET en todas las plataformas. Para más información, consulte Configuración de variables de entorno.

   Nota

   Por ejemplo, si el identificador del secreto es https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07, la referencia será @Microsoft.KeyVault(SecretUri=https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07).

   

8. Seleccione Aceptar para conservar la nueva configuración de la aplicación.

9. Seleccione otra vez Nueva configuración de la aplicación. En el cuadro de diálogo Agregar o editar la configuración de la aplicación, escriba la siguiente información y seleccione Aceptar:

   Configuración	Descripción
   Nombre	CREDENTIALS__KEY
   Clave	Obtenga el identificador del secreto cosmos-readwrite-key en el almacén de claves que creó anteriormente en este tutorial. Especifique el identificador con el formato siguiente: @Microsoft.KeyVault(SecretUri=<secret-identifier>).

10. De nuevo en la página Configuración, seleccione Guardar para actualizar la configuración de la aplicación web.

    

11. Espere unos minutos para que la aplicación web se reinicie con la nueva configuración de la aplicación. En este momento, la nueva configuración de la aplicación debe indicar que son una referencia del almacén de claves.

    

12. Seleccione Información general en el menú de navegación. Seleccione Examinar para ver la aplicación con las credenciales rellenadas.

    

Pasos siguientes

• Para configurar un firewall para Azure Cosmos DB, consulte el artículo sobre la compatibilidad con un firewall.
• Para configurar el punto de conexión de servicio de red virtual, vea el artículo Protección del acceso a una cuenta de Azure Cosmos DB con el uso de un punto de conexión de servicio de red virtual de Azure.