Conecte-se ao Azure usando uma conexão de serviço do Azure Resource Manager

Artigo
04/08/2024

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

Você pode usar uma conexão de serviço do Azure Resource Manager para conectar-se aos recursos do Azure com a autenticação principal de serviço ou uma identidade de serviço gerenciada pelo Azure. Caso use uma conexão de serviço do Resource Manager, você poderá usar um pipeline para implantar em um recurso do Azure, como um aplicativo do Serviço de Aplicativo do Azure, sem autenticar toda vez.

Há várias opções para se conectar ao Azure usando as conexões de serviço do Azure Resource Manager:

Entidade de serviço ou identidade gerenciada com federação de identidade de carga de trabalho

Entidade de serviço com segredo
Identidade gerenciada atribuída pelo agente

Para conhecer outros tipos de conexões e obter informações gerais sobre como criar e usar conexões, consulte Conexões de serviço para builds e versões.

Criar uma conexão de serviço do Azure Resource Manager que use a federação de identidade de workload

A Federação de identidade de Workload usa o OpenID Connect (OIDC) para autenticar com recursos protegidos do Microsoft Entra sem usar segredos.

Recomendamos usar essa abordagem se todos os itens a seguir forem verdadeiros para seu cenário:

Você tem a função Proprietário para sua assinatura do Azure.
Você não está se conectando ao Azure Stack ou a uma Nuvem do Azure Governamental.
Todas as tarefas de extensões do Marketplace que você usa foram atualizadas para oferecer suporte à federação de identidade de carga de trabalho.

Crie uma nova conexão de serviço de federação de identidade de carga de trabalho

No projeto do Azure DevOps, acesse Configurações do projeto>Conexões de serviço.

Para saber mais, confira Abra as configurações do projeto.
Selecione Nova conexão de serviço e Azure Resource Manager.
Selecione Federação de identidade de carga de trabalho (automática).

Especifique os seguintes parâmetros:

Parâmetro	Descrição
Subscription	Selecione uma assinatura existente do Azure. Se não aparecer nenhuma assinatura ou instância do Azure, consulte Solucionar problemas de conexões de serviço do Azure Resource Manager.
Grupo de recursos	Deixe esse campo em branco para permitir que os usuários acessem todos os recursos que estão definidos na assinatura. Para restringir o acesso do usuário aos recursos, coloque um nome de grupo de recursos. Os usuários só podem acessar os recursos definidos para este grupo de recursos.
Service connection name	Obrigatório. O nome que você irá usar para se referir a essa conexão de serviço nas propriedades da tarefa. Não nome da sua assinatura do Azure.

Após criar a nova conexão de serviço, copie o nome da conexão e cole-o no seu código como o valor para azureSubscription.
Para implantar em um recurso específico do Azure, a tarefa precisa de mais dados sobre esse recurso. Vá para o recurso no portal do Azure e copie os dados em seu código. Por exemplo, para implantar um aplicativo Web, copie o nome do aplicativo do Serviço de Aplicativo do Azure e cole-o no seu código como o valor para WebAppName.

Converta uma conexão de serviço existente do Azure Resource Manager para usar a federação de identidade de workload

Você pode converter rapidamente uma conexão de serviço do Azure Resource Manager existente a fim de usar a federação de identidades de workload para autenticação em vez de uma entidade de serviço. Você poderá usar a ferramenta de conversão de conexão de serviço dentro do Azure DevOps se sua conexão de serviço atender a esses requisitos:

O Azure DevOps criou originalmente a conexão de serviço. Se criar sua conexão de serviço manualmente, você não poderá convertê-la com a ferramenta de conversão de conexão de serviço, pois o Azure DevOps não tem permissões para modificar suas próprias credenciais.
Apenas um projeto usa a conexão de serviço. Não é possível converter conexões de serviços entre projetos.

Para poder converter uma conexão de serviço:

No projeto do Azure DevOps, acesse Configurações do projeto>Conexões de serviço.

Para saber mais, confira Abra as configurações do projeto.
Selecione a conexão de serviço que você quer converter para usar a identidade do workload.
Selecione Converter.

Se você tiver uma credencial de entidade de serviço existente com um segredo expirado, verá uma opção diferente para converter.
Selecione Converter novamente para confirmar que você deseja criar uma nova conexão de serviço.

A conversão pode levar alguns minutos. Se quiser reverter a conexão, reverta dentro de sete dias.

Converter várias conexões de serviço do Azure Resource Manager com um script

Use um script para atualizar várias conexões de serviço de uma só vez para agora usar a federação de identidades de carga de trabalho para autenticação.

Este exemplo de script do PowerShell requer dois parâmetros: organização do Azure DevOps (exemplo: https://dev.azure.com/fabrikam-tailspin) e projeto do Azure DevOps (exemplo: Space game web agent). Em seguida, o script recupera as conexões de serviço associadas para seu projeto e organização do Azure DevOps. Você deverá confirmar que deseja converter cada conexão de serviço associada que não usa a federação de identidades de carga de trabalho. Se você confirmar, o script usará a API REST do Azure DevOps para atualizar cada conexão de serviço para agora usar a federação de identidades de carga de trabalho. O script requer o PowerShell 7.3 ou posterior e o Azure CLI para ser executado. Salve o script em um arquivo .ps1 e execute-o usando o 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)'"
}

Reverter uma conexão existente do serviço Azure Resource Manager que usa um segredo da entidade de serviço

Você pode reverter uma conexão de serviço automática convertida com seu segredo por sete dias. Após sete dias, crie manualmente um novo segredo.

Se criar e converter sua conexão de serviço manualmente, você não poderá revertê-la com a ferramenta de conversão de conexão de serviço, pois o Azure DevOps não tem permissões para modificar suas próprias credenciais.

Para reverter uma conexão de serviço:

No projeto do Azure DevOps, acesse Pipelines>Conexões de serviço.
Escolha uma conexão de serviço existente para reverter.
Selecione Reverter conversão para o esquema original.
Selecione Reverter novamente para confirmar sua escolha.

Criar uma conexão de serviço do Azure Resource Manager que use um segredo da entidade de serviço

Recomendamos usar essa abordagem se todos os itens a seguir forem verdadeiros para seu cenário:

Você está conectado como o proprietário da organização do Azure Pipelines e da assinatura do Azure.
Você não precisa limitar ainda mais as permissões para recursos do Azure que os usuários acessam por meio da conexão de serviço.
Você não está se conectando ao Azure Stack ou a uma Nuvem do Azure Governamental.
Você não está se conectando do Azure DevOps Server 2019 ou versões anteriores do Team Foundation Server.

Para criar a conexão de serviço:

No projeto do Azure DevOps, acesse Configurações do projeto>Conexões de serviço.

No Team Foundation Server, selecione o ícone de Configurações na barra de menu superior para ir à página Serviços.

Para saber mais, confira Abra as configurações do projeto.
Selecione Nova conexão de serviço e Azure Resource Manager.

Insira ou selecione os seguintes parâmetros:

Parâmetro	Descrição
Nome da conexão	Obrigatório. O nome que você irá usar para se referir a essa conexão de serviço nas propriedades da tarefa. Não nome da sua assinatura do Azure.
Scope level	Selecione Assinatura ou Grupo de Gerenciamento. Grupos de gerenciamento são contêineres que ajudarão você a gerenciar o acesso, a política e a conformidade entre várias assinaturas.
Assinatura	Se você selecionar Assinatura para o escopo, selecione uma assinatura existente do Azure. Se não aparecer nenhuma assinatura ou instância do Azure, consulte Solucionar problemas de conexões de serviço do Azure Resource Manager.
Grupo de gerenciamento	Se você selecionar Grupo de Gerenciamento para o escopo, selecione um grupo de gerenciamento existente do Azure. Para obter mais informações, consulte Criar grupos de gerenciamento.
Grupo de Recursos	Deixe esse campo em branco para permitir que os usuários acessem todos os recursos que estão definidos na assinatura. Para restringir o acesso do usuário aos recursos, coloque um nome de grupo de recursos. Os usuários só podem acessar os recursos definidos para este grupo de recursos.

Depois que a nova conexão de serviço for criada:
- Se você usar o editor clássico, selecione o nome da conexão atribuído na configuração Assinatura do Azure do pipeline.
- Se você usar um arquivo YAML, copie o nome da conexão em seu código como o valor para azureSubscription.
Para implantar em um recurso específico do Azure, adicione à tarefa mais informações sobre o recurso:
- Se você usar o editor clássico, selecione os dados que serão adicionados à tarefa. Por exemplo, selecione o nome do Serviço de Aplicativo.
- Se você usar um arquivo YAML, acesse o recurso no portal do Azure. Copie os dados de que precisa e cole no código da tarefa. Por exemplo, para implantar um aplicativo Web, copie o nome do aplicativo do Serviço de Aplicativo e cole como o valor para WebAppName na tarefa YAML.

Observação

Quando você segue essa abordagem, o Azure DevOps se conecta ao Microsoft Entra ID e cria um registro de aplicativo com um segredo válido por três meses. Quando a conexão de serviço estiver prestes a vencer, o o Microsoft Entra ID exibirá este prompt: Um certificado ou segredo está expirando em breve. Crie um novo. Nesse cenário, você precisa atualizar a conexão de serviço.

Para atualizar a conexão de serviço, no portal do Azure DevOps, edite a conexão e selecione Verificar. Depois de salvar a edição, a conexão de serviço ficará válida por mais três meses.

Recomendamos usar a federação de identidades de cargas de trabalho em vez de criar um segredo. Se usar a federação de identidades de workload, você não precisará alternar segredos, e o registro do aplicativo manterá a finalidade pretendida. Para começar a usar a federação de identidades de cargas de trabalho, acesse a página de detalhes da conexão de serviço e selecione Converter. A conexão de serviço é convertida para usar a federação de identidade de workload em vez de um segredo. Para obter mais informações, consulte Converter uma conexão de serviço existente do Azure Resource Manager para usar a federação de identidades de workload.

Para mais informações, consulte Solucionar problemas de uma conexão de serviço do Azure Resource Manager.

Se você tiver problemas ao usar essa abordagem (como nenhuma assinatura sendo exibida na lista suspensa) ou se quiser limitar ainda mais as permissões de usuário, poderá usar uma entidade de serviço ou uma VM com uma identidade de serviço gerenciada.

Consulte Criar uma conexão de serviço do Azure Resource Manager que use uma entidade de serviço existente.

Se você quiser usar um conjunto predefinido de permissões de acesso e ainda não tiver uma entidade de serviço definida para esta finalidade, siga um destes tutoriais para criar uma entidade de serviço:
- Use o portal para criar um aplicativo do Microsoft Entra e uma entidade de serviço que possa acessar recursos
- Usar o Azure PowerShell para criar uma entidade de serviço do Azure que tenha um certificado
No projeto do Azure DevOps, acesse Configurações do projeto>Conexões de serviço.

No Team Foundation Server, selecione o ícone de Configurações na barra de menu superior para ir à página Serviços.

Para saber mais, confira Abra as configurações do projeto.
Selecione Nova conexão de serviço e Azure Resource Manager.
Selecione a opção Entidade de Serviço (manual) e insira os detalhes da entidade de serviço.
Para Nome da conexão, insira um nome para exibição para fazer referência a essa conexão de serviço.
Para Ambiente, selecione o nome do ambiente (Azure Cloud, Azure Stack ou Nuvem do Azure Governamental).
Se você não selecionar o Azure Cloud, insira a URL do ambiente. Para o Azure Stack, a URL do ambiente é algo do tipo https://management.local.azurestack.external.
Em Nível de escopo, selecione o escopo da conexão:
- Se você selecionar Assinatura, selecione uma assinatura existente do Azure. Se não aparecer nenhuma assinatura ou instância do Azure, consulte Solucionar problemas de conexões de serviço do Azure Resource Manager.
- Se você selecionar Grupo de Gerenciamento, selecione um grupo de gerenciamento existente do Azure. Para obter mais informações, consulte Criar grupos de gerenciamento.
Na caixa de diálogo de assinatura do Azure, insira estas informações sobre sua entidade de serviço:
- ID da assinatura
- Nome da assinatura
- ID da entidade de serviço
- A chave do cliente da entidade de serviço ou, se você tiver selecionado Certificado, insira o conteúdo das seções certificado e chave privada do arquivo *.pem.
- ID do locatário
Você pode obter essas informações baixando e executando um script do Azure PowerShell. Quando solicitado, insira o nome da assinatura, a senha, a função (opcional) e o tipo de nuvem, como Azure Cloud (padrão), Azure Stack ou uma Nuvem do Azure Governamental.
Selecione Verificar conexão para validar as configurações inseridas.
Depois que a nova conexão de serviço for criada:
- Se você usar a conexão de serviço na IU, selecione o nome da conexão que você atribuiu na caixa configuração Assinatura do Azure do pipeline.
- Se você usar a conexão de serviço em um arquivo YAML, copie o nome da conexão e cole-o no código como o valor para azureSubscription.
Se for preciso, modifique a entidade de serviço para expor as permissões apropriadas.

Para obter mais informações sobre como autenticar com uma entidade de serviço, consulte Usar o controle de acesso baseado em função para gerenciar o acesso aos seus recursos ou a postagem do blog Automatizar uma implantação de grupo de recursos do Azure usando uma entidade de serviço no Visual Studio.

Para mais informações, consulte Solucionar problemas de conexões de serviço do Azure Resource Manager.

Criar uma conexão de serviço do Azure Resource Manager para uma VM que usa uma identidade de serviço gerenciada

Observação

Para usar uma identidade de serviço gerenciado para autenticar, use um agente auto-hospedado em uma máquina virtual (VM) do Azure.

Você pode configurar agentes baseados em VMs do Azure com uma Identidade de Serviço Gerenciada do Azure no Microsoft Entra ID. Nesse caso, você usa a identidade atribuída pelo sistema (entidade de serviço) para conceder acesso aos agentes baseados em VM do Azure a qualquer recurso do Azure que dê suporte ao Microsoft Entra ID, como Cofre de Chaves do Azure, em vez de persistir credenciais no Azure DevOps para a conexão.

No projeto do Azure DevOps, acesse Configurações do projeto>Conexões de serviço.

No Team Foundation Server, selecione o ícone de Configurações na barra de menu superior para ir à página Serviços.

Para saber mais, confira Abra as configurações do projeto.
Selecione Nova conexão de serviço e Azure Resource Manager.
Selecione a opção Autenticação de Identidade Gerenciada.
Para Nome da conexão, insira um nome para exibição para usar ao fazer referência a essa conexão de serviço.
Para Ambiente, selecione o nome do ambiente (Azure Cloud, Azure Stack ou Nuvem do Azure Governamental).
Na caixa de diálogo Conexões, insira estes valores da sua assinatura:
- ID da assinatura
- Nome da assinatura
- ID do locatário
Depois que a nova conexão de serviço for criada:
- Se você usar a conexão de serviço na IU, selecione o nome da conexão que você atribuiu na caixa configuração Assinatura do Azure do pipeline.
- Se você usar a conexão de serviço em um arquivo YAML, copie o nome da conexão no código como o valor para azureSubscription.
Verifique se a VM (agente) tem as permissões apropriadas.

Por exemplo, se o código precisar chamar o Azure Resource Manager, atribua a função apropriada à VM usando o RBAC (controle de acesso baseado em função) no Microsoft Entra ID.

Para obter mais informações, consulte Como posso usar identidades gerenciadas para recursos do Azure? e Usar controle de acesso baseado em função para gerenciar o acesso aos recursos de assinatura do Azure.

Para obter mais informações sobre o processo, consulte Solucionar problemas de conexões de serviço do Azure Resource Manager.

Conectar-se a uma Nuvem do Azure Government

Para obter informações sobre como se conectar a uma Nuvem Governamental do Azure, consulte Conectar-se a partir de pipelines do Azure (Nuvem Governamental do Azure).

Conectar-se ao Azure Stack

Para obter mais informações sobre como se conectar ao Azure Stack, confira estes artigos:

Ajuda e suporte

Explore dicas de solução de problemas.
Obtenha conselhos sobre o Stack Overflow.
Publique suas perguntas, pesquise respostas ou sugira um recurso na Comunidade de Desenvolvedores de Azure DevOps.
Obtenha suporte para o Azure DevOps.