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

  • Artigo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

Você pode usar uma conexão de serviço do Azure Resource Manager para se conectar aos recursos do Azure por meio da autenticação da entidade de serviço ou por meio de uma identidade de serviço gerenciado do Azure. Se você usar uma conexão de serviço do Gerenciador de Recursos, poderá usar um pipeline para implantar em um recurso do Azure, como um aplicativo do Serviço de Aplicativo do Azure, sem autenticar cada vez.

Você tem várias opções para se conectar ao Azure usando 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
  • Principal de serviço com segredo
  • Identidade gerenciada atribuída pelo agente

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

Criar uma conexão de serviço do Azure Resource Manager que usa a federação de identidade de carga de trabalho

A federação de identidades de carga de trabalho usa o OpenID Connect (OIDC) para autenticar com recursos protegidos do Microsoft Entra sem usar segredos.

Recomendamos que você use essa abordagem se todos os seguintes itens forem verdadeiros para o 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 são atualizadas para dar suporte à federação de identidades de carga de trabalho.

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

  1. No projeto do Azure DevOps, vá para Configurações>do projeto Conexões de serviço.

    Para obter mais informações, consulte Abrir configurações do projeto.

  2. Selecione Nova conexão de serviço e, em seguida, selecione Azure Resource Manager.

    Captura de tela que mostra a escolha de um tipo de conexão de serviço de identidade de carga de trabalho.

  3. Selecione Federação de identidades de carga de trabalho (automática).

    Captura de tela que mostra a seleção de um tipo de conexão de serviço de identidade de carga de trabalho.

  4. Especifique os parâmetros seguintes:

    Parâmetro Description
    Subscrição Selecione uma assinatura existente do Azure. Se não aparecerem subscrições ou instâncias do Azure, consulte Resolução de problemas de ligações de serviço do Azure Resource Manager.
    Grupo de Recursos Deixe em branco para permitir que os usuários acessem todos os recursos definidos na assinatura. Para restringir o acesso do usuário aos recursos, insira um nome de grupo de recursos. Os usuários podem acessar somente os recursos definidos para esse grupo de recursos.
    Nome da conexão de serviço Obrigatório. O nome que você usa para se referir a essa conexão de serviço nas propriedades da tarefa. Não é o nome da sua assinatura do Azure.

  5. Depois que a nova conexão de serviço for criada, copie o nome da conexão e cole-o em seu código como o valor de azureSubscription.

  6. 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 para o 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 em seu código como o valor de WebAppName.

Converter uma conexão de serviço existente do Azure Resource Manager para usar a federação de identidade de carga de trabalho

Você pode converter rapidamente uma conexão de serviço existente do Azure Resource Manager para usar a federação de identidade de carga de trabalho para autenticação em vez de uma entidade de serviço. Você pode usar a ferramenta de conversão de conexão de serviço no Azure DevOps se sua conexão de serviço atender a estes requisitos:

  • O Azure DevOps criou originalmente a conexão de serviço. Se você criar manualmente sua conexão de serviço, não poderá converter a conexão de serviço usando a ferramenta de conversão de conexão de serviço porque 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ço entre projetos.

Para converter uma conexão de serviço:

  1. No projeto do Azure DevOps, vá para Configurações>do projeto Conexões de serviço.

    Para obter mais informações, consulte Abrir configurações do projeto.

  2. Selecione a conexão de serviço que você deseja converter para usar a identidade da carga de trabalho.

  3. Selecione Converter.

    Captura de tela que mostra a seleção de conversão para credenciais federadas.

    Se você tiver uma credencial de entidade de serviço existente com um segredo expirado, verá uma opção diferente para converter.

    Captura de tela que mostra a opção de converter para usar credenciais federadas quando você tem um certificado expirado.

  4. Selecione Converter novamente para confirmar que deseja criar uma nova conexão de serviço.

    A conversão pode demorar alguns minutos. Se você quiser reverter a conexão, você deve revertê-la 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 identidade 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ê será solicitado a confirmar que deseja converter cada conexão de serviço associada que não usa federação de identidade 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 mais recente e a CLI do Azure 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 do 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 você criar e converter manualmente sua conexão de serviço, não poderá reverter a conexão de serviço usando a ferramenta de conversão de conexão de serviço porque o Azure DevOps não tem permissões para modificar suas próprias credenciais.

Para reverter uma conexão de serviço:

  1. No projeto Azure DevOps, vá para Conexões do Serviço de Pipelines>.

  2. Selecione uma conexão de serviço existente para reverter.

  3. Selecione Reverter conversão para o esquema original.

    Captura de tela que mostra a seleção de reverter para uma credencial federada.

  4. Selecione Reverter novamente para confirmar sua escolha.

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

Recomendamos que você use essa abordagem se todos os seguintes itens forem verdadeiros para o seu cenário:

  • Você está conectado como 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 de versões anteriores do Team Foundation Server.

Para criar a conexão de serviço:

  1. No projeto do Azure DevOps, vá para Configurações>do projeto Conexões de serviço.

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

    Para obter mais informações, consulte Abrir configurações do projeto.

  2. Selecione Nova conexão de serviço e, em seguida, selecione Azure Resource Manager.

    Captura de tela que mostra a escolha de um tipo de conexão de serviço.

  3. Insira ou selecione os seguintes parâmetros:

    Parâmetro Description
    Nome da Ligação Obrigatório. O nome que você usa para se referir a essa conexão de serviço nas propriedades da tarefa. Não é o nome da sua assinatura do Azure.
    Nível de âmbito Selecione Subscrição ou Grupo de Gestão. Os grupos de gerenciamento são contêineres que ajudam a gerenciar o acesso, a política e a conformidade em várias assinaturas.
    Subscrição Se você selecionar Assinatura para o escopo, selecione uma assinatura existente do Azure. Se não aparecerem subscrições ou instâncias do Azure, consulte Resolução de problemas de ligações de serviço do Azure Resource Manager.
    Grupo de Gestão Se você selecionar Grupo de Gerenciamento para o escopo, selecione um grupo de gerenciamento do Azure existente. Para obter mais informações, consulte Criar grupos de gerenciamento.
    Grupo de Recursos Deixe em branco para permitir que os usuários acessem todos os recursos definidos na assinatura. Para restringir o acesso do usuário aos recursos, insira um nome de grupo de recursos. Os usuários podem acessar somente os recursos definidos para esse grupo de recursos.

  4. Depois que a nova conexão de serviço for criada:

    • Se você usar o editor clássico, selecione o nome de conexão atribuído na configuração de assinatura do Azure do seu pipeline.
    • Se você usar um arquivo YAML, copie o nome da conexão em seu código como o valor para azureSubscription.

  5. Para implantar em um recurso específico do Azure, adicione mais informações sobre o recurso à tarefa:

    • Se você usar o editor clássico, selecione os dados a serem adicionados à tarefa. Por exemplo, selecione o nome do Serviço de Aplicativo.
    • Se você usar um arquivo YAML, vá para o recurso no portal do Azure. Copie os dados necessários 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-o como o valor para WebAppName a tarefa YAML.

Nota

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

Para atualizar uma 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 é válida por mais três meses.

Recomendamos que você use a federação de identidades de carga de trabalho em vez de criar um segredo. Se você usar a federação de identidades de carga de trabalho, não precisará alternar segredos e o registro de aplicativo manterá a finalidade pretendida. Para começar a usar a federação de identidades de carga de trabalho, vá para 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 carga de trabalho 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 carga de trabalho.

Para obter 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 mostrada na lista suspensa) ou se quiser limitar ainda mais as permissões do usuário, poderá usar uma entidade de serviço ou uma máquina virtual com uma identidade de serviço gerenciado.

Criar uma conexão de serviço do Azure Resource Manager que usa uma entidade de serviço existente

  1. Se você quiser usar um conjunto predefinido de permissões de acesso e ainda não tiver uma entidade de serviço definida para essa finalidade, siga um destes tutoriais para criar uma nova entidade de serviço:

  2. No projeto do Azure DevOps, vá para Configurações>do projeto Conexões de serviço.

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

    Para obter mais informações, consulte Abrir configurações do projeto.

  3. Selecione Nova conexão de serviço e, em seguida, selecione Azure Resource Manager.

    Captura de tela que mostra a escolha de um tipo de conexão de serviço.

  4. Selecione a opção Entidade de serviço (manual) e, em seguida, insira os detalhes da entidade de serviço.

    Captura de tela que mostra a abertura da versão completa da caixa de diálogo de serviço.

  5. Em Nome da conexão, insira um nome para exibição a ser usado para fazer referência a essa conexão de serviço.

  6. Em Ambiente, selecione o nome do ambiente (Azure Cloud, Azure Stack ou Azure Government Cloud).

  7. Se não selecionar a Nuvem do Azure, introduza o URL do ambiente. Para o Azure Stack, a URL do ambiente é algo como https://management.local.azurestack.external.

  8. Em Nível de escopo, selecione o escopo da conexão:

    • Se você selecionar Assinatura, selecione uma assinatura existente do Azure. Se não aparecerem subscrições ou instâncias do Azure, consulte Resolução de problemas de ligações de serviço do Azure Resource Manager.
    • Se você selecionar Grupo de Gerenciamento, selecione um grupo de gerenciamento do Azure existente. Para obter mais informações, consulte Criar grupos de gerenciamento.

  9. Na caixa de diálogo Assinatura do Azure, insira as seguintes informações sobre sua entidade de serviço:

    • ID da subscrição
    • Nome da subscrição
    • ID da entidade de serviço
    • A chave do cliente da entidade de serviço ou, se você selecionou Certificado, insira o conteúdo das seções de certificado e chave privada do arquivo *.pem .
    • ID de Inquilino do

    Você pode obter essas informações baixando e executando um script do Azure PowerShell. Quando lhe for pedido, introduza o nome da subscrição, a palavra-passe, a função (opcional) e o tipo de nuvem, como a Nuvem do Azure (predefinida), o Azure Stack ou uma Nuvem do Azure Governamental.

  10. Selecione Verificar conexão para validar as configurações inseridas.

  11. Depois que a nova conexão de serviço for criada:

    • Se você usar a conexão de serviço na interface do usuário, selecione o nome da conexão que você atribuiu na configuração de assinatura do Azure do seu pipeline.
    • Se você usar a conexão de serviço em um arquivo YAML, copie o nome da conexão e cole-o em seu código como o valor para azureSubscription.

  12. Se necessário, modifique a entidade de serviço para expor as permissões apropriadas.

    Para obter mais informações sobre a autenticação usando uma entidade de serviço, consulte Usar controle de acesso baseado em função para gerenciar o acesso aos recursos de assinatura do Azure 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 obter 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 com uma VM que usa uma identidade de serviço gerenciado

Nota

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

Você pode configurar agentes baseados em VM do Azure para usar uma Identidade de Serviço Gerenciado do Azure na ID do Microsoft Entra. Nesse cenário, você usa a identidade atribuída ao sistema (entidade de serviço) para conceder aos agentes baseados em VM do Azure acesso a qualquer recurso do Azure que ofereça suporte à ID do Microsoft Entra, como uma instância do Cofre da Chave do Azure, em vez de persistir as credenciais no Azure DevOps para a conexão.

  1. No projeto do Azure DevOps, vá para Configurações>do projeto Conexões de serviço.

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

    Para obter mais informações, consulte Abrir configurações do projeto.

  2. Selecione Nova conexão de serviço e, em seguida, selecione Azure Resource Manager.

    Captura de tela que mostra a escolha de um tipo de conexão de serviço.

  3. Selecione a opção Autenticação de identidade gerenciada.

    Captura de tela que mostra ir para as configurações de identidade do serviço gerenciado.

  4. Em Nome da conexão, insira um nome para exibição a ser usado quando você se referir a essa conexão de serviço.

  5. Em Ambiente, selecione o nome do ambiente (Azure Cloud, Azure Stack ou Azure Government Cloud).

  6. Na caixa de diálogo conexões, insira os seguintes valores da sua assinatura:

    • ID da subscrição
    • Nome da subscrição
    • ID de Inquilino do

  7. Depois que a nova conexão de serviço for criada:

    • Se você usar a conexão de serviço na interface do usuário, selecione o nome da conexão que você atribuiu na configuração de assinatura do Azure do seu pipeline.
    • Se você usar a conexão de serviço em um arquivo YAML, copie o nome da conexão em seu código como o valor para azureSubscription.

  8. Verifique se a VM (agente) tem as permissões apropriadas.

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

    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 (Azure Government Cloud).

Ligar ao Azure Stack

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

Ajuda e suporte