Conectar con Azure mediante una conexión de servicio de Azure Resource Manager

Artículo
04/07/2024

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Puede usar una conexión de servicio de Azure Resource Manager para conectarse a recursos de Azure a través de la autenticación de entidad de servicio o una identidad de servicio administrado de Azure. Si usa una conexión de servicio de Azure Resource Manager, podrá usar un proceso para implementarlo en un recurso de Azure, como una aplicación de App Service sin autenticarse cada vez.

Cuenta con varias opciones para conectarse a Azure mediante conexiones de servicio de Azure Resource Manager:

Entidad de servicio o identidad administrada con federación de identidades de carga de trabajo

Entidad de servicio con secreto
Identidad administrada asignada por agente

Para conocer otros tipos de conexiones y obtener información general sobre cómo crear y usar conexiones, consulte Conexiones de servicio para compilaciones y versiones.

Crear una conexión de servicio de Azure Resource Manager mediante la federación de identidades de carga de trabajo

La federación de identidades de carga de trabajo usa OpenID Connect (OIDC) para autenticarse con recursos protegidos de Microsoft Entra sin utilizar secretos.

Se recomienda usar este método si se cumplen todos los siguientes criterios en su caso:

Tiene el rol Propietario para la suscripción de Azure.
No se va a conectar a Azure Stack ni a una nube de Azure Government.
Las tareas de extensiones de Marketplace que usa se han actualizado para admitir la federación de identidades de carga de trabajo.

Creación de una nueva conexión del servicio de federación de identidades de carga de trabajo

En el proyecto de Azure DevOps, vaya a Configuración de proyecto>Conexiones de servicio.

Para obtener más información, consultes Abrir la configuración de proyecto.
Seleccione Nueva conexión de servicio y luego Azure Resource Manager.
Seleccione Federación de identidades de carga de trabajo (automática).

Especifique los parámetros siguientes:

Parámetro	Descripción
Suscripción	Seleccione una suscripción de Azure existente. Si no aparece ninguna suscripción o instancia de Azure, consulte Solucionar problemas de conexiones de servicio de Azure Resource Manager.
Grupo de recursos	Deje este campo vacío para permitir que los usuarios accedan a todos los recursos definidos en la suscripción. Para restringir el acceso de usuario a los recursos, escriba un nombre de grupo de recursos. Los usuarios solo podrán acceder a los recursos definidos de ese grupo de recursos.
Nombre de conexión de servicio	Necesario. El nombre que usará para hacer referencia a esta conexión de servicio en las propiedades de la tarea. No el nombre de la suscripción de Azure.

Una vez creada la nueva conexión de servicio, copie el nombre de conexión y péguelo en el código como valor de azureSubscription.
Para realizar la implementación en un recurso de Azure específico, la tarea necesita más datos sobre ese recurso. Vaya al recurso en el Azure Portal y copie los datos en el código. Por ejemplo, para implementar una aplicación web, copie el nombre de la aplicación App Service de Azure y péguelo en el código como valor de WebAppName.

Convertir una conexión de servicio de Azure Resource Manager existente para usar la federación de identidades de carga de trabajo

Puede convertir rápidamente una conexión de servicio de Azure Resource Manager existente para usar la federación de identidades de carga de trabajo como autenticación en lugar de una entidad de servicio. Puede usar la herramienta de conversión de conexión de servicio en Azure DevOps si la conexión de servicio cumple estos requisitos:

Azure DevOps creó originalmente la conexión de servicio. Si crea manualmente la conexión de servicio, no podrá convertirla con la herramienta de conversión en cuestión porque Azure DevOps no tiene los permisos para modificar sus propias credenciales.
Solo un proyecto usa la conexión de servicio. No se pueden convertir conexiones de servicio entre proyectos.

Cómo convertir una conexión de servicio:

En el proyecto de Azure DevOps, vaya a Configuración de proyecto>Conexiones de servicio.

Para obtener más información, consultes Abrir la configuración de proyecto.
Seleccione la conexión de servicio que desee convertir para usar la identidad de carga de trabajo.
Seleccione Convertir.

Si tiene una credencial de entidad de servicio existente con un secreto expirado, verá una opción diferente para convertir.
Seleccione Convertir de nuevo para confirmar que desea crear una nueva conexión de servicio.

Este proceso de conversión puede tardar unos minutos. Si desea revertir la conexión, deberá hacerlo en un plazo de siete días.

Convertir varias conexiones de servicio de Azure Resource Manager con un script

Utilice un script para actualizar varias conexiones de servicio a la vez para que ahora utilicen la federación de identidades de carga de trabajo para la autenticación.

Este script de PowerShell de ejemplo requiere dos parámetros: organización de Azure DevOps (ejemplo: https://dev.azure.com/fabrikam-tailspin) y proyecto de Azure DevOps (ejemplo: Space game web agent). A continuación, el script recupera las conexiones de servicio asociadas para el proyecto y la organización de Azure DevOps. Se le pedirá que confirme que desea convertir cada conexión de servicio asociada que no use la federación de identidades de carga de trabajo. Si lo confirma, el script usará la API REST de Azure DevOps para actualizar cada conexión de servicio para que ahora use la federación de identidades de carga de trabajo. Para ejecutarse, el script necesita PowerShell 7.3 o posterior y la CLI de Azure. Guarde el script en un archivo .ps1 y ejecútelo mediante PowerShell 7.

#!/usr/bin/env pwsh
<# 
.SYNOPSIS 
    Convert multiple Azure Resource Manager service connection(s) to use Workload identity federation

.LINK
    https://aka.ms/azdo-rm-workload-identity-conversion

.EXAMPLE
    ./convert_azurerm_service_connection_to_oidc_simple.ps1 -Project <project> -OrganizationUrl https://dev.azure.com/<organization>
#> 

#Requires -Version 7.3

param ( 
    [parameter(Mandatory=$true,HelpMessage="Name of the Azure DevOps Project")]
    [string]
    [ValidateNotNullOrEmpty()]
    $Project,

    [parameter(Mandatory=$true,HelpMessage="Url of the Azure DevOps Organization")]
    [uri]
    [ValidateNotNullOrEmpty()]
    $OrganizationUrl
) 
$apiVersion = "7.1"
$PSNativeCommandArgumentPassing = "Standard" 

#-----------------------------------------------------------
# Log in to Azure
$azdoResource = "499b84ac-1321-427f-aa17-267ca6975798" # application id of Azure DevOps 
az login --allow-no-subscriptions --scope ${azdoResource}/.default
$OrganizationUrl = $OrganizationUrl.ToString().Trim('/')

#-----------------------------------------------------------
# Retrieve the service connection
$getApiUrl = "${OrganizationUrl}/${Project}/_apis/serviceendpoint/endpoints?authSchemes=ServicePrincipal&type=azurerm&includeFailed=false&includeDetails=true&api-version=${apiVersion}"
az rest --resource $azdoResource -u "${getApiUrl} " -m GET --query "sort_by(value[?authorization.scheme=='ServicePrincipal' && data.creationMode=='Automatic' && !(isShared && serviceEndpointProjectReferences[0].projectReference.name!='${Project}')],&name)" -o json `
        | Tee-Object -Variable rawResponse | ConvertFrom-Json | Tee-Object -Variable serviceEndpoints | Format-List | Out-String | Write-Debug
if (!$serviceEndpoints -or ($serviceEndpoints.count-eq 0)) {
    Write-Warning "No convertible service connections found"
    exit 1
}

foreach ($serviceEndpoint in $serviceEndpoints) {
    # Prompt user to confirm conversion
    $choices = @(
        [System.Management.Automation.Host.ChoiceDescription]::new("&Convert", "Converting service connection '$($serviceEndpoint.name)'...")
        [System.Management.Automation.Host.ChoiceDescription]::new("&Skip", "Skipping service connection '$($serviceEndpoint.name)'...")
        [System.Management.Automation.Host.ChoiceDescription]::new("&Exit", "Exit script")
    )
    $prompt = $serviceEndpoint.isShared ? "Convert shared service connection '$($serviceEndpoint.name)'?" : "Convert service connection '$($serviceEndpoint.name)'?"
    $decision = $Host.UI.PromptForChoice([string]::Empty, $prompt, $choices, $serviceEndpoint.isShared ? 1 : 0)

    if ($decision -eq 0) {

        Write-Host "$($choices[$decision].HelpMessage)"
    } elseif ($decision -eq 1) {
        Write-Host "$($PSStyle.Formatting.Warning)$($choices[$decision].HelpMessage)$($PSStyle.Reset)"
        continue 
    } elseif ($decision -ge 2) {
        Write-Host "$($PSStyle.Formatting.Warning)$($choices[$decision].HelpMessage)$($PSStyle.Reset)"
        exit 
    }

    # Prepare request body
    $serviceEndpoint.authorization.scheme = "WorkloadIdentityFederation"
    $serviceEndpoint.data.PSObject.Properties.Remove('revertSchemeDeadline')
    $serviceEndpoint | ConvertTo-Json -Depth 4 | Write-Debug
    $serviceEndpoint | ConvertTo-Json -Depth 4 -Compress | Set-Variable serviceEndpointRequest
    $putApiUrl = "${OrganizationUrl}/${Project}/_apis/serviceendpoint/endpoints/$($serviceEndpoint.id)?operation=ConvertAuthenticationScheme&api-version=${apiVersion}"
    # Convert service connection
    az rest -u "${putApiUrl} " -m PUT -b $serviceEndpointRequest --headers content-type=application/json --resource $azdoResource -o json `
            | ConvertFrom-Json | Set-Variable updatedServiceEndpoint

    $updatedServiceEndpoint | ConvertTo-Json -Depth 4 | Write-Debug
    if (!$updatedServiceEndpoint) {
        Write-Debug "Empty response"
        Write-Error "Failed to convert service connection '$($serviceEndpoint.name)'"
        exit 1
    }
    Write-Host "Successfully converted service connection '$($serviceEndpoint.name)'"
}

Revertir una conexión de servicio de Azure Resource Manager existente que usa un secreto de entidad de servicio

Puede revertir una conexión de servicio automática convertida con su secreto durante siete días. Después de siete días, cree manualmente un nuevo secreto.

Si crea y convierte manualmente la conexión de servicio, no podrá revertirla con la herramienta de conversión en cuestión porque Azure DevOps no tiene los permisos para modificar sus propias credenciales.

Cómo revertir una conexión de servicio:

En el proyecto de Azure DevOps, vaya a Pipelines (Procesos)>Conexiones de servicio.
Seleccione una conexión de servicio existente para revertirla.
Seleccione Revertir conversión al esquema original.
Seleccione Revertir de nuevo para confirmar su elección.

Crear una conexión de servicio de Azure Resource Manager que usa un secreto de entidad de servicio

Se recomienda usar este método si se cumplen todos los siguientes criterios en su caso:

Ha iniciado sesión como propietario de la organización de Azure Pipelines y la suscripción de Azure.
No es necesario limitar aún más los permisos de los recursos de Azure a los que los usuarios acceden a través de la conexión de servicio.
No se va a conectar a Azure Stack ni a una nube de Azure Government.
No se va a conectar desde Azure DevOps Server 2019 o versiones anteriores de Team Foundation Server.

Cómo crear la conexión de servicio

En el proyecto de Azure DevOps, vaya a Configuración de proyecto>Conexiones de servicio.

En Team Foundation Server, seleccione el icono Configuración en la barra de menú superior para ir a la página Servicios.

Para obtener más información, consultes Abrir la configuración de proyecto.
Seleccione Nueva conexión de servicio y luego Azure Resource Manager.

Escriba o seleccione los siguientes parámetros:

Parámetro	Descripción
Nombre de la conexión	Necesario. El nombre que usará para hacer referencia a esta conexión de servicio en las propiedades de la tarea. No el nombre de la suscripción de Azure.
Nivel de ámbito	Seleccione Suscripción o Grupo de administración. Los grupos de administración son contenedores que ayudan a administran el acceso, las directivas y el cumplimiento de varias suscripciones.
Suscripción	Si selecciona Suscripción para este ámbito y elija una suscripción de Azure existente. Si no aparece ninguna suscripción o instancia de Azure, consulte Solucionar problemas de conexiones de servicio de Azure Resource Manager.
Grupo de administración	Si selecciona Grupo de administración para este ámbito, elija un grupo de administración de Azure existente. Para obtener más información, consulte Crear grupos de administración.
Grupo de recursos	Deje este campo vacío para permitir que los usuarios accedan a todos los recursos definidos en la suscripción. Para restringir el acceso de usuario a los recursos, escriba un nombre de grupo de recursos. Los usuarios solo podrán acceder a los recursos definidos de ese grupo de recursos.

Una vez creada la nueva conexión de servicio:
- Si usa el editor clásico, seleccione el nombre de conexión que asignó en la configuración de la suscripción de Azure para su proceso.
- Si usa un archivo YAML, copie el nombre de conexión en el código como valor de azureSubscription.
Para hacer la implementación en un recurso específico de Azure, agregue más información sobre el recurso a la tarea:
- Si usa el editor clásico, seleccione los datos para agregarlos a la tarea. Por ejemplo, seleccione el nombre del App Service.
- Si usa un archivo YAML, acceda al recurso en el portal de Azure. Copie los datos que necesita y péguelos en el código de la tarea. Por ejemplo, para implementar una aplicación web, copie el nombre de la aplicación App Service y péguelo como valor de WebAppName en el YAML de la tarea.

Nota:

Al seguir este enfoque, Azure DevOps se conecta con Microsoft Entra ID y crea un registro de aplicación con un secreto válido durante tres meses. Cuando la conexión de servicio está cerca de expirar, Microsoft Entra ID muestra este mensaje: Pronto expirará un certificado o secreto. Cree uno nuevo. En este escenario, debe actualizar la conexión de servicio.

Para actualizar una conexión de servicio, en el portal de Azure DevOps, edite la conexión y luego seleccione Comprobar. Después de guardar los cambios, la conexión de servicio será válida durante otros tres meses.

Le recomendamos usar la federación de identidades de carga de trabajo en lugar de crear un secreto. Si usa la federación de identidades de carga de trabajo, no es necesario rotar los secretos y el registro de aplicaciones sigue su uso previsto. Para empezar a usar la federación de identidades de carga de trabajo, vaya a la página de detalles de conexión de servicio y seleccione Convertir. La conexión de servicio se convierte para usar la federación de identidades de carga de trabajo en lugar de un secreto. Para obtener más información, consulte Convertir una conexión de servicio de Azure Resource Manager existente para usar la federación de identidades de carga de trabajo.

Para obtener más información, consulte Solución de problemas de una conexión de servicio de Azure Resource Manager.

Si tiene problemas al usar este método (por ejemplo, no aparece ninguna suscripción en la lista desplegable), o si desea limitar aún más los permisos de los usuarios, puede usar una entidad de servicio o una máquina virtual con una identidad de servicio administrada.

Crear una conexión de servicio de Azure Resource Manager que usa una entidad de servicio existente

Si quiere usar un conjunto predefinido de permisos de acceso y aún no tiene una entidad de servicio definida para este fin, siga uno de estos tutoriales para crear una nueva entidad de servicio:
- Usar el portal para crear una aplicación de Microsoft Entra y una entidad de servicio que pueda acceder a los recursos
- Uso de Azure PowerShell para crear una entidad de servicio de Azure que incluya un certificado
En el proyecto de Azure DevOps, vaya a Configuración de proyecto>Conexiones de servicio.

En Team Foundation Server, seleccione el icono Configuración en la barra de menú superior para ir a la página Servicios.

Para obtener más información, consultes Abrir la configuración de proyecto.
Seleccione Nueva conexión de servicio y luego Azure Resource Manager.
Elija la opción Entidad de servicio (manual) y escriba los detalles de la Entidad de servicio.
En Nombre de conexión, escriba un nombre de visualización que se usará para hacer referencia a esta conexión de servicio.
En Entorno, seleccione el nombre del entorno (Azure Cloud, Azure Stack o Nube de Azure Government).
Si no selecciona Azure Cloud, escriba la dirección URL del entorno. En el caso de Azure Stack, la dirección URL del entorno es algo similar a https://management.local.azurestack.external.
En Nivel de ámbito, seleccione el ámbito de la conexión:
- Si selecciona Suscripción, elija una suscripción de Azure existente. Si no aparece ninguna suscripción o instancia de Azure, consulte Solucionar problemas de conexiones de servicio de Azure Resource Manager.
- Si selecciona Grupo de administración, elija un grupo de administración de Azure existente. Para obtener más información, consulte Crear grupos de administración.
En el cuadro de diálogo de la suscripción de Azure, escriba la información siguiente sobre la entidad de servicio:
- Id. de suscripción
- Nombre de suscripción
- ID de entidad de servicio
- O bien, la clave de cliente de la entidad de servicio o, si ha seleccionado Certificado, escriba el contenido de las secciones certificado y clave privada del archivo *.pem.
- Id. de inquilino
Puede obtener esta información descargando y ejecutando un script de Azure PowerShell. Cuando se le pida, escriba el nombre de la suscripción, la contraseña, el rol (opcional) y el tipo de nube, como Azure Cloud (el valor predeterminado), Azure Stack o una nube de Azure Government.
Seleccione Comprobar conexión para validar la configuración elegida.
Una vez creada la nueva conexión de servicio:
- Si usa la conexión de servicio en la interfaz de usuario, seleccione el nombre de la conexión que haya asignado en la configuración de suscripción de Azure en su proceso.
- Si usa la conexión de servicio en un archivo YAML, copie el nombre de la conexión y péguelo en el código como valor de azureSubscription.
En caso necesario, modifique la entidad de servicio para exponer los permisos adecuados.

Para obtener más información sobre la autenticación mediante una entidad de servicio, consulte Uso del control de acceso basado en roles para administrar el acceso a los recursos de suscripción de Azure o el artículo de blog Automatizar una implementación de grupo de recursos de Azure mediante una entidad de servicio en Visual Studio.

Para obtener más información, consulte Solución de problemas de conexiones de servicio de Azure Resource Manager.

Crear una conexión de servicio de Azure Resource Manager a una VM que usa una identidad de servicio administrada

Nota:

Para usar una identidad de servicio administrada para autenticarse, debe usar un agente autohospedado en una máquina virtual (VM) de Azure.

Puede configurar agentes basados en máquinas virtuales de Azure con una Identidad de servicio administrada de Azure (Azure Managed Service Identity) en Microsoft Entra ID. En este escenario, puede usar la identidad asignada por el sistema (entidad de servicio) para conceder a los agentes basados en máquinas virtuales de Azure acceso a cualquier recurso de Azure que admita Microsoft Entra ID, como una instancia de Azure Key Vault, en lugar de conservar las credenciales en Azure DevOps para la conexión.

En el proyecto de Azure DevOps, vaya a Configuración de proyecto>Conexiones de servicio.

En Team Foundation Server, seleccione el icono Configuración en la barra de menú superior para ir a la página Servicios.

Para obtener más información, consultes Abrir la configuración de proyecto.
Seleccione Nueva conexión de servicio y luego Azure Resource Manager.
Seleccione la opción Autenticación de identidad administrada.
En Nombre de conexión, escriba un nombre de visualización que se usará cuando haga referencia a esta conexión de servicio.
En Entorno, seleccione el nombre del entorno (Azure Cloud, Azure Stack o Nube de Azure Government).
En el cuadro de diálogo de conexiones, escriba los valores siguientes de la suscripción:
- Id. de suscripción
- Nombre de suscripción
- Id. de inquilino
Una vez creada la nueva conexión de servicio:
- Si usa la conexión de servicio en la interfaz de usuario, seleccione el nombre de la conexión que haya asignado en la configuración de suscripción de Azure en su proceso.
- Si usa la conexión de servicio en un archivo YAML, copie el nombre de la conexión en el código como valor de azureSubscription.
Asegúrese de que la máquina virtual (agente) tenga los permisos adecuados.

Por ejemplo, si el código necesita llamar a Azure Resource Manager, asigne a la máquina virtual el rol adecuado mediante el control de acceso basado en roles (RBAC) en Microsoft Entra ID.

Para obtener más información, consulte ¿Cómo puedo usar identidades administradas para recursos de Azure? y Uso del control de acceso basado en roles para administrar el acceso a los recursos de suscripción de Azure.

Para obtener más información sobre el proceso, consulte Solución de problemas de conexiones de servicio de Azure Resource Manager.

Conexión a una nube de Azure Government

Para obtener información sobre cómo conectarse a una nube de Azure Government, consulte Conectarse a través de Azure Pipelines (Nube de Azure Government).

Conexión a Azure Stack

Para obtener más información sobre cómo conectarse a Azure Stack, lea estos artículos:

Ayuda y soporte técnico

Busque y consulte sugerencias para la resolución de problemas.
Vea consejos sobre Stack Overflow.
Publique sus preguntas, busque respuestas o sugiera una característica en la Comunidad de desarrolladores de Azure DevOps.
Reciba soporte técnico para Azure DevOps.