Migración de una aplicación para usar conexiones sin contraseña con Azure Cosmos DB for NoSQL

Las solicitudes de aplicación a Azure Cosmos DB for NoSQL deben autenticarse. Aunque hay varias opciones para autenticarse en Azure Cosmos DB, debe priorizar las conexiones sin contraseña en las aplicaciones siempre que sea posible. Los métodos de autenticación tradicionales que usan cadenas de conexión con contraseñas o claves secretas crean riesgos y complicaciones de seguridad. Visite el centro de Conexiones sin contraseña para servicios de Azure para obtener más información sobre las ventajas de pasar a conexiones sin contraseña.

El siguiente tutorial explica cómo migrar una aplicación existente para conectarse a Azure Cosmos DB for NoSQL mediante conexiones sin contraseña en lugar de una solución basada en claves.

Configuración de roles y usuarios para la autenticación de desarrollo local

Al desarrollar localmente con autenticación sin contraseña, asegúrese de que a la cuenta de usuario que se conecta a Cosmos DB se le asigna un rol con los permisos correctos para realizar operaciones de datos. Actualmente, Azure Cosmos DB for NoSQL no incluye roles integrados para las operaciones de datos, pero puede crear el suyo propio mediante la CLI de Azure o PowerShell.

Los roles constan de una colección de permisos o acciones que un usuario puede realizar, como lectura, escritura y eliminación. Puede obtener más información sobre cómo configurar el control de acceso basado en roles (RBAC) en la documentación de configuración de seguridad de Cosmos DB.

Creación del rol personalizado

1. Asignación de un rol mediante el comando az role definition create. Pase el nombre de la cuenta y el grupo de recursos de Cosmos DB, seguido de un cuerpo de JSON que defina el rol personalizado. En el ejemplo siguiente se crea un rol denominado PasswordlessReadWrite con permisos para leer y escribir elementos en contenedores de Cosmos DB. El rol también tiene como ámbito el nivel de cuenta mediante /.

   az cosmosdb sql role definition create \
       --account-name <cosmosdb-account-name> \
       --resource-group  <resource-group-name> \
       --body '{
       "RoleName": "PasswordlessReadWrite",
       "Type": "CustomRole",
       "AssignableScopes": ["/"],
       "Permissions": [{
           "DataActions": [
               "Microsoft.DocumentDB/databaseAccounts/readMetadata",
               "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
               "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
           ]
       }]
   }'
   

2. Cuando se complete el comando, copie el valor de identificador del campo name y péguelo en algún lugar para su uso posterior.

3. Asigne el rol que ha creado a la cuenta de usuario o a la entidad de servicio que se conectará a Cosmos DB. Durante el desarrollo local, por lo general, será su propia cuenta la que haya iniciado sesión en una herramienta de desarrollo como Visual Studio o en la CLI de Azure. Recupere los detalles de su cuenta mediante el comando az ad user.

   az ad user show --id "<your-email-address>"
   

4. Copie el valor de la propiedad id fuera de los resultados y péguelo en algún lugar para su uso posterior.

5. Asigne el rol personalizado que creó a la cuenta de usuario mediante el comando az cosmosdb sql role assignment create y los identificadores que copió anteriormente.

   az cosmosdb sql role assignment create \
       --account-name <cosmosdb-account-name> \
       --resource-group  <resource-group-name> \
       --scope "/" \
       --principal-id <your-user-id> \
       --role-definition-id <your-custom-role-id> 
   

Inicio de sesión en Azure localmente

En el caso del desarrollo local, asegúrese de realizar la autenticación con la misma cuenta de Microsoft Entra a la que ha asignado el rol. Puede autenticarse a través de herramientas de desarrollo populares, como la CLI de Azure o Azure PowerShell. Las herramientas de desarrollo con las que puede autenticarse varían en todos los idiomas.

CLI de Azure

Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:

az login

Visual Studio

Seleccione el botón Iniciar sesión en la parte superior derecha de Visual Studio.

Inicie sesión con la cuenta de Microsoft Entra a la que asignó un rol anteriormente.

Visual Studio Code

Hay que instalar la CLI de Azure para trabajar con DefaultAzureCredential mediante Visual Studio Code.

En el menú principal de Visual Studio Code, vaya a Terminal > Nueva terminal.

Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:

az login

PowerShell

Inicie sesión en Azure mediante PowerShell a través del siguiente comando:

Connect-AzAccount

Migración del código de la aplicación para usar conexiones sin contraseña

.NET

1. Para usar DefaultAzureCredential en una aplicación .NET, instale el paquete Azure.Identity:

   dotnet add package Azure.Identity
   

2. En la parte superior del archivo, agregue el código siguiente:

   using Azure.Identity;
   

3. Identifique las ubicaciones del código que crean un objeto CosmosClient para conectarse a Azure Cosmos DB. Actualice su código para que coincida con el ejemplo siguiente.

   DefaultAzureCredential credential = new();
   
   using CosmosClient client = new(
       accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT"),
       tokenCredential: credential
   );
   

Go

1. Para usar DefaultAzureCredential en una aplicación Go, instale el módulo azidentity:

   go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity
   

2. En la parte superior del archivo, agregue el código siguiente:

   import (
       "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
   )
   

3. Identifique las ubicaciones del código que crean una instancia Client para conectarse a Azure Cosmos DB. Actualice su código para que coincida con el ejemplo siguiente:

   cred, err := azidentity.NewDefaultAzureCredential(nil)
   if err != nil {
       // handle error
   }
   
   endpoint := os.Getenv("COSMOS_ENDPOINT")
   client, err := azblob.NewClient(endpoint, cred, nil)
   if err != nil {
       // handle error
   }
   

Java

1. Para usar DefaultAzureCredential en una aplicación Java, instale el paquete azure-identity mediante uno de los métodos siguientes:

   1. Inclusión del archivo BOM.
   2. Inclusión de una dependencia directas.

2. En la parte superior del archivo, agregue el código siguiente:

   import com.azure.identity.DefaultAzureCredentialBuilder;
   

3. Identifique las ubicaciones del código que crean un objeto CosmosClient o CosmosAsyncClient para conectarse a Azure Cosmos DB. Actualice su código para que coincida con el ejemplo siguiente:

   DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
       .build();
   String endpoint = System.getenv("COSMOS_ENDPOINT");
   
   CosmosClient client = new CosmosClientBuilder()
       .endpoint(endpoint)
       .credential(credential)
       .consistencyLevel(ConsistencyLevel.EVENTUAL)
       .buildClient();
   

Node.js

1. Para usar DefaultAzureCredential en una aplicación Node.js, instale el paquete @azure/identity:

   npm install --save @azure/identity
   

2. En la parte superior del archivo, agregue el código siguiente:

   import { DefaultAzureCredential } from "@azure/identity";
   

3. Identifique las ubicaciones del código que crean un objeto CosmosClient para conectarse a Azure Cosmos DB. Actualice su código para que coincida con el ejemplo siguiente:

   const credential = new DefaultAzureCredential();
   const endpoint = process.env.COSMOS_ENDPOINT;
   
   const cosmosClient = new CosmosClient({ 
       endpoint, 
       aadCredentials: credential
   });
   

Python

1. Para usar DefaultAzureCredential en una aplicación Python, instale el paquete azure-identity:

   pip install azure-identity
   

2. En la parte superior del archivo, agregue el código siguiente:

   from azure.identity import DefaultAzureCredential
   

3. Identifique las ubicaciones del código que crean un objeto BlobServiceClient para conectarse a Azure Blob Storage. Actualice su código para que coincida con el ejemplo siguiente:

   credential = DefaultAzureCredential()
   endpoint = os.environ["COSMOS_ENDPOINT"]
   
   client = CosmosClient(
       url = endpoint,
       credential = credential
   )
   

Ejecución de la aplicación de forma local

Después de realizar estos cambios de código, ejecute la aplicación localmente. La nueva configuración debe recoger las credenciales locales, como la CLI de Azure, Visual Studio o IntelliJ. Los roles que asigne al usuario de desarrollo local en Azure permitirán a la aplicación conectarse al servicio de Azure localmente.

Configuración del entorno de hospedaje de Azure

Una vez que la aplicación se ha configurado para usar conexiones sin contraseña y se ejecuta localmente, el mismo código se puede autenticar en los servicios de Azure después de implementarla en Azure. En las secciones siguientes se explica cómo configurar una aplicación implementada para conectarse a Azure Cosmos DB mediante una identidad administrada.

Creación de la identidad administrada

Puede crear una identidad administrada asignada por el usuario mediante el Azure Portal o la CLI de Azure. La aplicación usa la identidad para autenticarse en otros servicios.

Azure Portal

1. En la parte superior del Azure Portal, busque Identidades administradas. Seleccione el resultado de Identidades administradas.
2. Seleccione + Crear en la parte superior de la página de información general de Identidades administradas.
3. En la pestaña Datos básicos, escriba los valores siguientes:
   • Suscripción: Seleccione la opción de suscripción que desee.
   • Grupo de recursos: Seleccione el grupo de recursos deseado.
   • Región: seleccione una región cercana a su ubicación.
   • Nombre: Escriba un nombre reconocible para la identidad, como MigrationIdentity.
4. En la parte inferior de la página, seleccione Revisar y crear.
5. Cuando finalicen las comprobaciones de validación, seleccione Crear. Azure crea una nueva identidad asignada por el usuario.

Una vez creado el recurso, seleccione Ir al recurso para ver los detalles de la identidad administrada.

CLI de Azure

Use el comando az identity create para crear una identidad administrada asignada por el usuario:

az identity create --name MigrationIdentity --resource-group <your-resource-group>

Asociación de la identidad administrada a la aplicación web

Debe configurar la aplicación web para usar la identidad administrada que ha creado. Asigne la identidad a la aplicación mediante el Azure Portal o la CLI de Azure.

Azure Portal

Complete los pasos siguientes en el Azure Portal para asociar una identidad a la aplicación. Estos mismos pasos se aplican a los siguientes servicios de Azure:

• Azure Spring Apps
• Azure Container Apps
• Máquinas virtuales de Azure
• Azure Kubernetes Service

1. Vaya a la página de información general de la aplicación web.

2. En el menú de navegación de la izquierda, seleccione Identidad.

3. En la página Identidad, cambie a la pestaña Asignado por el usuario.

4. Seleccione + Agregar para abrir el control flotante Agregar identidad administrada asignada por el usuario.

5. Seleccione la suscripción que usó anteriormente para crear la identidad.

6. Busque MigrationIdentity por nombre y selecciónelo en los resultados de la búsqueda.

7. Seleccione Agregar para asociar la identidad a la aplicación.

   

CLI de Azure

Use los siguientes comandos de la CLI de Azure para asociar una identidad a la aplicación:

Recupere el id. de la identidad administrada que creó mediante el comando az identity show. Copie el valor de salida que se usará en el paso siguiente.

az identity show --name MigrationIdentity -g <your-identity-resource-group-name> --query id

Azure App Service

Puede asignar una identidad administrada a una instancia de Azure App Service con el comando az webapp identity assign.

az webapp identity assign \
    --resource-group <resource-group-name> \
    --name <webapp-name>
    --identities <managed-identity-id>

Azure Spring Apps

Puede asignar una identidad administrada a una instancia de Azure Spring Apps con el comando az spring app identity assign.

az spring app identity assign \
    --resource-group <resource-group-name> \
    --name <app-name> \
    --service <service-name>
    --user-assigned <managed-identity-id>

Azure Container Apps

Puede asignar una identidad administrada a una máquina virtual con el comando az containerapp identity assign.

az containerapp identity assign \
    --resource-group <resource-group-name> \
    --name <app-name>
    --user-assigned <managed-identity-id>

Máquinas virtuales de Azure

Puede asignar una identidad administrada a una máquina virtual con el comando az vm identity assign.

az vm identity assign \
    --resource-group <resource-group-name> \
    --name <virtual-machine-name>
    --identities <managed-identity-id>

Azure Kubernetes Service

Puede asignar una identidad administrada a una instancia de Azure Kubernetes Service (AKS) con el comando az aks update.

az aks update \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --enable-managed-identity \
    --assign-identity <managed-identity-id> \
    --assign-kubelet-identity <managed-identity-id>

Asignación de roles a la identidad administrada

Conceda permisos a la identidad administrada mediante la asignación del rol personalizado que ha creado, tal como hizo con el usuario de desarrollo local.

Para asignar un rol en el nivel de recurso mediante la CLI de Azure, primero debe recuperar el id. de recurso mediante el comando az cosmosdb show. Puede filtrar las propiedades de salida mediante el parámetro --query.

az cosmosdb show \
    --resource-group '<resource-group-name>' \
    --name '<cosmosdb-name>' \
    --query id

Copie el id. de salida del comando anterior. A continuación, puede asignar roles mediante el comando az role assignment de la CLI de Azure.

az role assignment create \
    --assignee "<your-managed-identity-name>" \
    --role "PasswordlessReadWrite" \
    --scope "<cosmosdb-resource-id>"

Actualización del código de la aplicación

Debe configurar el código de la aplicación para buscar la identidad administrada específica que creó cuando se implemente en Azure. En algunos escenarios, establecer explícitamente la identidad administrada para la aplicación también impide que otras identidades del entorno se detecten y usen automáticamente.

1. En la página de información general de la identidad administrada, copie el valor del id. de cliente en el Portapapeles.

2. Aplique los siguientes cambios específicos de idioma:

   .NET

   Cree un objeto DefaultAzureCredentialOptions y páselo a DefaultAzureCredential. Establezca la propiedad ManagedIdentityClientId en el identificador de cliente.

   DefaultAzureCredential credential = new(
       new DefaultAzureCredentialOptions
       {
           ManagedIdentityClientId = managedIdentityClientId
       });
   

   Go

   Establezca la variable de entorno AZURE_CLIENT_ID en el identificador de cliente de identidad administrada. DefaultAzureCredential lee esta variable de entorno.

   Java

   Llame al método managedIdentityClientId. Pásele el identificador de cliente.

   DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
       .managedIdentityClientId(managedIdentityClientId)
       .build();
   

   Node.js

   Cree un objeto DefaultAzureCredentialClientIdOptions con su propiedad managedIdentityClientId establecida en el identificador de cliente. Pase ese objeto al constructor DefaultAzureCredential.

   const credential = new DefaultAzureCredential({
     managedIdentityClientId
   });
   

   Python

   Establezca el parámetro managed_identity_client_id del constructor DefaultAzureCredential en el identificador de cliente.

   credential = DefaultAzureCredential(
       managed_identity_client_id = managed_identity_client_id
   )
   

3. Vuelva a implementar el código en Azure después de realizar este cambio para que se apliquen las actualizaciones de configuración.

Prueba de la aplicación

Después de implementar el código actualizado, vaya a la aplicación hospedada en el explorador. La aplicación debe poder conectarse a Cosmos DB con éxito. Tenga en cuenta que las asignaciones de roles pueden tardar varios minutos en propagarse a través del entorno de Azure. Ahora la aplicación está configurada para ejecutarse localmente y en un entorno de producción sin que los desarrolladores tengan que administrar los secretos en la propia aplicación.

Pasos siguientes

En este tutorial, ha aprendido a migrar una aplicación a conexiones sin contraseña.

Puede leer los siguientes recursos para explorar los conceptos que se describen en este artículo con más detalle:

• Autorización del acceso a blobs mediante Microsoft Entra ID
• Para obtener más información sobre .NET, consulte Introducción a .NET en 10 minutos.