Uso de identidades administradas con servicios de Azure para conectarse a Azure Cosmos DB for NoSQL

Artículo
10/01/2024

SE APLICA A: NoSQL

Diagrama de la ubicación actual (

En este artículo se revisan los pasos necesarios para crear identidades administradas que se usarán con una aplicación implementada conectada a Azure Cosmos DB for NoSQL.

Las identidades administradas son uno de los muchos tipos de recursos de identidad de Microsoft Entra ID para que las aplicaciones los usen al conectarse a los servicios que admiten la autenticación de Microsoft Entra. Las identidades administradas se pueden usar en lugar de credenciales tradicionales de propiedad de recursos, como las claves. En Azure, las identidades administradas proporcionan una manera de que las aplicaciones obtengan un token de Microsoft Entra para autenticarse en los servicios de Azure sin necesidad de escribir una gran cantidad de código de autenticación.

Puede usar Microsoft Entra para autenticarse en servicios de Azure, incluidos, entre otros:

SQL de Azure
Azure AI
Azure Cosmos DB
Azure Storage
Azure Event Hubs
Azure Container Registry

Puede usar identidades administradas para representar la entidad de seguridad que se autentica en un servicio de Azure desde otros servicios de Azure, incluidos, entre otros:

Azure Kubernetes Service
Azure Container Apps
Azure Virtual Machines
Funciones de Azure
Azure App Service
Azure Spring Apps
Azure Service Fabric

Las identidades administradas permiten varios escenarios seguros en los que varios servicios de Azure se pueden conectar entre sí. Estos son algunos ejemplos:

Creación de una identidad administrada asignada por el sistema para una aplicación en Azure Spring Apps para conectarse a una cuenta de Azure SQL y consultarla
Uso de una única identidad administrada asignada por el usuario tanto con Azure Kubernetes Service como con Azure Functions para emitir solicitudes a una cuenta de Azure AI
Uso de una identidad administrada para una cuenta de Azure Cosmos DB para almacenar claves en Azure Key Vault

Para más información, consulte Identidades administradas para los recursos de Azure.

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.
Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.
- Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.
- En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.
- Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

Si opta por usar Azure PowerShell en un entorno local:
- Instale la versión más reciente del módulo Az de PowerShell.
- Conéctese a su cuenta de Azure mediante el cmdlet Connect-AzAccount.
Si decide usar Azure Cloud Shell:
- Para más información, consulte Introducción a Azure Cloud Shell.

Creación de un servicio de Azure con una identidad administrada asignada por el sistema

Cree un nuevo servicio de Azure con una identidad administrada asignada por el sistema. En esta sección se crea un recurso de Azure Container Instances.

Use az container create para crear una nueva instancia de contenedor. Configure la cuenta para usar una identidad administrada asignada por el sistema mediante el parámetro assign-identity.

az container create \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-new-container>" \
    --image mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled \
    --cpu 1 \
    --memory 2 \
    --assign-identity

Obtenga los detalles de la identidad administrada asignada por el sistema mediante az container show y una consulta JMESPath.

az container show \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-container>" \
    --query "identity"

Revise la salida de este comando. Debería incluir los identificadores únicos para la identidad y el inquilino.

{
  "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "type": "SystemAssigned",
  "userAssignedIdentities": null
}

Cree un nuevo archivo de Bicep para definir una nueva instancia de contenedor. Asigne al archivo el nombre container-instance.bicep. Defina estas propiedades en la instancia de contenedor.

	Valor
`name`	Use un parámetro denominado `instanceName`
`location`	Defínala en la ubicación del grupo de recursos
`identity.type`	`SystemAssigned`
`properties.osType`	`Linux`
`properties.containers[0].name`	`aspnet-sample`
`properties.containers[0].properties.image`	`mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled`
`properties.containers[0].properties.resources.requests.cpu`	`1`
`properties.containers[0].properties.resources.requests.memoryInGB`	`2`

metadata description = 'Create Azure Container Instance resource with system-assigned managed identity.'

@description('Name of the Azure Container Instances resource.')
param instanceName string

resource instance 'Microsoft.ContainerInstance/containerGroups@2023-05-01' = {
  name: instanceName
  location: resourceGroup().location
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    osType: 'Linux'
    containers: [
      {
        name: 'aspnet-sample'
        properties: {
          image: 'mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled'
          resources: {
            requests: {
              cpu: 1
              memoryInGB: 2
            }
          }
        }
      }
    ]
  }
}

output systemAssignedIdentity object = instance.identity

Cree un nuevo archivo de parámetros de Bicep denominado container-instance.bicepparam. En este archivo de parámetros, cree un nombre exclusivo para la instancia de contenedor mediante el parámetro instanceName.
```
using './container-instance.bicep'

param instanceName = '<name-of-new-container-instance>'
```

Implemente la plantilla de Bicep mediante az deployment group create. Especifique el nombre de la plantilla de Bicep, el archivo de parámetros y el grupo de recursos de Azure.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters "container-instance.bicepparam" \
    --template-file "container-instance.bicep"

Revise la salida de la implementación. La salida contiene el objeto de identidad de la instancia de contenedor en la propiedad properties.outputs.systemAssignedIdentity.value.
```
{
  "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "type": "SystemAssigned"
}
```

Inicie sesión en Azure Portal (https://portal.azure.com).
Escriba Azure Container Instances en la barra de búsqueda global.
En Servicios, seleccione Instancias de contenedor.
En el panel Instancias de contenedor, seleccione Crear.

En el panel Aspectos básicos, configure las siguientes opciones y, a continuación, seleccione Revisar y crear:

	Valor
Suscripción	Seleccione su suscripción a Azure.
Grupo de recursos	Cree un grupo de recursos nuevo o seleccione uno existente
Nombre del contenedor	Proporcione un nombre único global.
Región	Seleccione una región de Azure compatible para su suscripción

Captura de pantalla del panel

Sugerencia

Puede dejar cualquier opción con sus valores predeterminados.

En el panel Revisar y crear, espere a que la validación de la cuenta finalice correctamente y seleccione Crear.
El portal va automáticamente al panel Implementación. Espere a que la implementación se complete.
Una vez completada la implementación, seleccione Ir al recurso para ir al nuevo recurso de Azure Container Instances.
En el panel de la nueva instancia de contenedor, seleccione Identidad en la sección Configuración del menú de servicios.
En el panel Identidad, habilite la identidad administrada asignada por el sistema; para ello, establezca la opción Estado en Activado. A continuación, seleccione Guardar y resuelva las indicaciones para confirmar el cambio.
Una vez que la identidad administrada asignada por el sistema esté lista, revise el valor de la propiedad Id. de objeto (principal). El valor de esta propiedad se trata de un identificador único para la identidad.

Sugerencia

En esta captura de pantalla de ejemplo, el identificador único de la identidad administrada asignada por el sistema es bbbbbbbb-1111-2222-3333-cccccccccccc.

Cree un objeto que represente un contenedor mediante New-AzContainerInstanceObject y almacénelo en una variable denominada $container. A continuación, use ese objeto contenedor para crear una nueva instancia de contenedor con New-AzContainerGroup. Configure la cuenta para usar una identidad administrada asignada por el sistema al establecer el parámetro IdentityType en SystemAssigned.

$parameters = @{
    Name = "aspnet-sample"
    Image = "mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled"
    RequestCpu = 1 
    RequestMemoryInGb = 2
}
$container = New-AzContainerInstanceObject @parameters

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-new-container>"
    Container = $container
    OsType = "Linux"
    Location = "<azure-region>"
    IdentityType = "SystemAssigned"
}
New-AzContainerGroup @parameters

Obtenga los detalles de la identidad administrada asignada por el sistema mediante Get-AzContainerGroup y de Format-List solo con la propiedad Identity.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-container>"
}
Get-AzContainerGroup @parameters | Format-List Identity

Revise la salida de este comando. Debería incluir los identificadores únicos para la identidad y el inquilino.

Identity : {
             "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
             "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
             "type": "SystemAssigned"
           }

Creación de una identidad administrada asignada por el usuario

Cree una identidad administrada asignada por el usuario que se pueda usar con uno o varios servicios de Azure de forma portátil.

Use az identity create para crear una identidad administrada asignada por el usuario en el grupo de recursos de Azure.

az identity create \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-new-managed-identity>"

Obtenga la lista de identidades administradas asignadas por el usuario en el grupo de recursos mediante az identity list.
```
az identity list \
    --resource-group "<name-of-existing-resource-group>"    
```

Revise la salida de este comando. Registre el valor del campo id, ya que este identificador de recursos completo se usa para asignar la identidad administrada asignada por el usuario al recurso de Azure.

{
  "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned",
  "location": "<azure-location>",
  "name": "msdocs-identity-example-user-assigned",
  "principalId": "cccccccc-dddd-eeee-3333-444444444444",
  "resourceGroup": "msdocs-identity-example",
  "systemData": null,
  "tags": {},
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Nota:

Para este ejemplo, el valor de id sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo.

Cree un archivo de Bicep para definir una identidad administrada asignada por el usuario y asigne el nombre user-assigned-managed-identity.bicep al archivo. Establezca estas propiedades mínimas:

	Valor
`name`	Use un parámetro opcional denominado `identityName` y genere un valor predeterminado único
`location`	Defínala en la ubicación del grupo de recursos

metadata description = 'Create a user-assigned managed identity.'

param identityName string = uniqueString(subscription().id, resourceGroup().id)

resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: identityName
  location: resourceGroup().location
}

output id string = identity.id
output name string = identity.name

Implemente la plantilla de Bicep mediante az deployment group create. Especifique el nombre de la plantilla de Bicep y el grupo de recursos de Azure.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file "user-assigned-managed-identity.bicep"

Revise la salida de la implementación. La salida contiene el identificador único de la identidad administrada en la propiedad properties.outputs.name.value. Registre este valor, ya que tendrá que usarlo al crear un nuevo recurso de Azure más adelante en esta guía.
```
{
  "type": "String",
  "value": "msdocs-identity-example-user-assigned"
}
```
Nota:

En este ejemplo, name.value sería msdocs-identity-example-user-assigned. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo.

Escriba Identidad administrada en la barra de búsqueda global.
En Servicios, seleccione Identidades administradas.
En el panel Instancias de contenedor, seleccione Crear.

En el panel Aspectos básicos, configure las siguientes opciones y, a continuación, seleccione Revisar y crear:

	Valor
Suscripción	Seleccione su suscripción a Azure.
Grupo de recursos	Cree un grupo de recursos nuevo o seleccione uno existente
Región	Seleccione una región de Azure compatible para su suscripción
Nombre	Proporcione un nombre único global.

Captura de pantalla del panel

En el panel Revisar y crear, espere a que la validación de la cuenta finalice correctamente y seleccione Crear.
El portal va automáticamente al panel Implementación. Espere a que la implementación se complete.
Espere a que se complete la implementación de la identidad administrada.

Cree una nueva identidad administrada asignada por el usuario mediante New-AzUserAssignedIdentity en el grupo de recursos de Azure.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-new-managed-identity>"
    Location = "<azure-region>"
}
New-AzUserAssignedIdentity @parameters

Use Get-AzUserAssignedIdentity para obtener una lista de identidades administradas asignadas por el usuario en el grupo de recursos.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
}
Get-AzUserAssignedIdentity @parameters | Format-List Name, Id

Revise la salida de este comando. Registre el valor del campo Id, ya que este identificador de recursos completo se usa para asignar la identidad administrada asignada por el usuario al recurso de Azure.
```
Name : msdocs-identity-example-user-assigned
Id   : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned
```
Nota:

Para este ejemplo, el valor de Id sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo.

Crear un servicio de Azure con una identidad administrada asignada por el usuario

Asigne la identidad administrada asignada por el usuario creada anteriormente a un nuevo servicio de host de Azure. En esta sección se crea un recurso de aplicación web de Azure App Services.

Cree un nuevo plan de App Service mediante az appservice plan create.

az appservice plan create \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-new-plan>"

Asigne la identidad administrada asignada por el usuario a una nueva aplicación web con az webapp create. Use el campo id registrado anteriormente en esta guía como valor del parámetro ssign-identity.

az webapp create \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-web-app>" \
    --plan "<name-of-existing-plan>" \
    --assign-identity "<resource-id-recorded-earlier>"

Obtenga los detalles de todas las identidades asignadas a esta cuenta mediante az webapp show y una consulta JMESPath.

az webapp show \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-account>" \
    --query "identity"

Revise la salida de este comando. Debe incluir la identidad administrada asignada por el usuario.

{
  "principalId": null,
  "tenantId": null,
  "type": "UserAssigned",
  "userAssignedIdentities": {
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned": {
      "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
      "principalId": "cccccccc-dddd-eeee-3333-444444444444"
    }
  }
}

Cree otro archivo de Bicep denominado app-service-web-app.bicep y defina un plan y una aplicación web de Azure App Service. Establezca estas propiedades para esos recursos:

	Resource	Valor
`name`	Identidad administrada existente	Use un parámetro denominado `identityName`
`name`	Plan de App Service	Use un parámetro denominado `planName`
`location`	Plan de App Service	Defínala en la ubicación del grupo de recursos
`name`	Aplicación web	Use un parámetro denominado `webAppName`
`location`	Aplicación web	Defínala en la ubicación del grupo de recursos
`identity.type`	`UserAssigned`
`identity.userAssignedIdentities.{identity.id}`	`{}`
`properties.serverFarmId`	`plan.id`

metadata description = 'Creates an Azure App Service plan and web app with a user-assigned managed identity.'

@description('The name of the app service plan.')
param planName string

@description('The name of the web app.')
param webAppName string

@description('The name of the user-assigned managed identity.')
param identityName string

resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' existing = {
  name: identityName
}

resource plan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: planName
  location: resourceGroup().location
}

resource webApp 'Microsoft.Web/sites@2023-12-01' = {
  name: webAppName
  location: resourceGroup().location
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity.id}': {}
    }
  }
  properties: {
    serverFarmId: plan.id
  }
}

output userAssignedIdentity object = webApp.identity

Cree un archivo de parámetros de Bicep denominado app-service-web-app.bicepparam. En este archivo de parámetros, cree un nombre exclusivo para la aplicación web y plan mediante los parámetros planName y webAppName respectivamente. A continuación, proporcione el nombre de la identidad administrada asignada por el usuario como valor del parámetro identityName.
```
using './app-service-web-app.bicep'

param planName = '<name-of-new-app-service-plan>'
param webAppName = '<name-of-new-web-app>'
param identityName = '<name-of-existing-managed-identity>'
```

Implemente la plantilla de Bicep mediante az deployment group create. Especifique el nombre de la plantilla de Bicep, el archivo de parámetros y el grupo de recursos de Azure.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters "app-service-web-app.bicepparam" \
    --template-file "app-service-web-app.bicep"

Revise la salida de la implementación. La salida contiene el objeto de identidad de la instancia de contenedor en la propiedad properties.outputs.userAssignedIdentity.value.

{
  "type": "UserAssigned",
  "userAssignedIdentities": {
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned": {
      "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
      "principalId": "cccccccc-dddd-eeee-3333-444444444444"
    }
  }
}

Escriba Aplicación web en la barra de búsqueda global.
En Servicios, seleccione App Services.
En el panel App Services, seleccione Crear y, a continuación, Aplicación web.

En el panel Aspectos básicos, configure las siguientes opciones y, a continuación, seleccione Revisar y crear:

	Valor
Suscripción	Seleccione su suscripción a Azure.
Grupo de recursos	Cree un grupo de recursos nuevo o seleccione uno existente
Nombre	Proporcione un nombre único global.
Plan	Cree un nuevo plan o seleccione uno existente.

Captura de pantalla del panel

En el panel Revisar y crear, espere a que la validación de la cuenta finalice correctamente y seleccione Crear.
El portal va automáticamente al panel Implementación. Espere a que la implementación se complete.
Una vez completada la implementación, seleccione Ir al recurso para ir al nuevo recurso de Azure Container Instances.
En el panel de la nueva instancia de contenedor, seleccione Identidad en la sección Configuración del menú de servicios.
En el panel Identidad, seleccione la opción Asignada por el usuario.
Seleccione Agregar para abrir un cuadro de diálogo para asignar identidades administradas asignadas por el usuario existentes. En el cuadro de diálogo, seleccione la identidad administrada asignada por el usuario existente y, a continuación, seleccione Agregar.
Por último, revise la lista de identidades administradas asignadas por el usuario asociadas a la aplicación web. Debería incluir el nombre de la identidad, el nombre del grupo de recursos y el identificador de suscripción.

Use New-AzWebApp para crear una nueva aplicación web de Azure App Service.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-new-web-app>"
    Location = "<azure-region>"
}
New-AzWebApp @parameters

Revise la aplicación web recién creada para establecer la propiedad identity.type en UserAssigned y agregue la identidad administrada asignada por el usuario existente a la propiedad identity.userAssignedIdentities. Para completar esta tarea, primero proporcione el campo id registrado anteriormente en esta guía como valor de la variable de shell identityId. A continuación, construya un objeto de carga y conviértelo en JSON. Por último, use Invoke-AzRestMethod con el verbo HTTP PATCH para actualizar la aplicación web existente.
```
$identityId = "<resource-id-recorded-earlier>"

$payload = @{
    identity = @{
        type = "UserAssigned"
        userAssignedIdentities = @{
            "$identityId" = @{}
        }
    }
} | ConvertTo-Json -Depth 3

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-web-app>"
    ResourceProviderName = 'Microsoft.Web'
    ResourceType = 'sites'
    ApiVersion = '2023-12-01'
    Method = 'PATCH'
    Payload = $payload
}
Invoke-AzRestMethod @parameters
```

Obtenga los detalles de todas las la identidades asignadas a la aplicación web mediante Get-AzWebApp, Select-Object y ConvertTo-Json solo con la propiedad Identity.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-web-app>"
}
Get-AzWebApp @parameters | Select-Object Identity | ConvertTo-Json -Depth 3

Revise la salida de este comando. Debería incluir los identificadores únicos para la identidad y el inquilino.

{
  "Identity": {
    "Type": "UserAssigned",
    "TenantId": null,
    "PrincipalId": null,
    "UserAssignedIdentities": {
      "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned": {
        "PrincipalId": "cccccccc-dddd-eeee-3333-444444444444",
        "ClientId": "11112222-bbbb-3333-cccc-4444dddd5555"
      }
    }
  }
}

Paso siguiente

Deshabilitación de la autenticación basada en certificados con Azure Cosmos DB for NoSQL

Compartir a través de

Uso de identidades administradas con servicios de Azure para conectarse a Azure Cosmos DB for NoSQL

Requisitos previos

Creación de un servicio de Azure con una identidad administrada asignada por el sistema

Creación de una identidad administrada asignada por el usuario

Crear un servicio de Azure con una identidad administrada asignada por el usuario

Paso siguiente

Comentarios

Recursos adicionales