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

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

Nota

Estamos implementando a nova experiência de criação de conexão de serviço do Azure. Recebê-lo em sua organização depende de vários fatores, e você ainda pode ver a experiência do usuário mais antiga.

Uma conexão de serviço do Azure Resource Manager permite que você se conecte a recursos do Azure, como o Azure Key Vault, a partir do seu pipeline. Essa conexão permite que você use um pipeline para implantar em recursos do Azure, como um aplicativo do Serviço de Aplicativo do Azure, sem precisar autenticar cada vez.

Você tem várias opções de autenticação para se conectar ao Azure com uma conexão de serviço do Azure Resource Manager. Recomendamos o uso da federação de identidade de carga de trabalho com um registo de aplicação ou identidade gerida. A federação de identidades de carga de trabalho elimina a necessidade de segredos e da gestão de segredos.

Opções recomendadas:

• Registro de aplicativo (automático) com de federação de identidade de carga de trabalho
• Identidade gerenciada que cria uma credencial de federação de identidade de carga de trabalho e se conecta a uma identidade gerenciada atribuída pelo usuário existente. Utilize esta opção quando não tiver permissão para criar um registo de aplicação.
• Registro de aplicativo ou identidade gerenciada (manual) com federação de identidade de carga de trabalho ou umsecreto . A configuração manual é mais demorada do que a configuração automática e só deve ser usada se você já tentou a opção automática.

Nota

Há outras opções de autenticação de conexão de serviço do Azure Resource Manager que não usam a federação de identidades de carga de trabalho. Essas opções estão disponíveis para compatibilidade com versões anteriores e casos excecionais, e não são recomendadas. Se você estiver configurando uma conexão de serviço pela primeira vez, use a federação de identidades de carga de trabalho. Se você tiver uma conexão de serviço existente, tente converter conexão de serviço para usar a federação de identidades de carga de trabalho primeiro.

• Registo automático da aplicação com uma chave secreta
• Identidade gerida atribuída ao agente
• Publicar perfil

Criar um registo de aplicação com federação de identidade de carga de trabalho (automática)

Você pode usar essa abordagem se todos os seguintes itens forem verdadeiros para o seu cenário:

• Tem a função Proprietário na sua subscrição do Azure.
• Você não está se conectando ao Azure Stack ou aos ambientes do Azure US Government .
• 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.

Com essa seleção, o Azure DevOps consulta automaticamente a assinatura, o grupo de gerenciamento ou o espaço de trabalho de Aprendizado de Máquina ao qual você deseja se conectar e cria uma federação de identidade de carga de trabalho para autenticaçã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 Nova conexão de serviço e, em seguida, selecione Azure Resource Manager e Avançar.

   

3. Selecione Registro de aplicativo (automático) com a credencial Federação de identidades de carga de trabalho.

   

4. Selecione um nível de escopo. Selecione Assinatura, Grupo de Gerenciamento ou Espaço de Trabalho de Aprendizado de Máquina. Os grupos de gerenciamento são contêineres que ajudam a gerenciar o acesso, a política e a conformidade em várias assinaturas. Um Espaço de Trabalho de Aprendizado de Máquina é o local para criar artefatos de aprendizado de máquina.

   • Para o escopo Assinatura, insira os seguintes parâmetros:

     Parâmetro	Description
     Subscrição	Obrigatório. Selecione a assinatura do Azure.
     Grupo de recursos	Opcional. Selecione o grupo de recursos do Azure.

   • Para o escopo do Grupo de Gerenciamento, selecione o grupo de gerenciamento do Azure.

   • Para o escopo do Espaço de Trabalho de Aprendizado de Máquina , insira os seguintes parâmetros:

     Parâmetro	Description
     Subscrição	Obrigatório. Selecione a assinatura do Azure.
     Grupo de Recursos	Obrigatório. Selecione o grupo de recursos que contém o espaço de trabalho.
     Espaço de trabalho de aprendizado de máquina	Obrigatório. Selecione o espaço de trabalho do Azure Machine Learning.

5. Insira um nome de conexão de serviço.

6. Opcionalmente, insira uma descrição para a conexão de serviço.

7. Selecione Conceder permissão de acesso a todos os pipelines para permitir que todos os pipelines usem essa conexão de serviço. Se você não selecionar essa opção, deverá conceder manualmente acesso a cada pipeline que usa essa conexão de serviço.

8. Selecione Guardar.

Criar uma conexão de serviço para uma identidade gerenciada atribuída ao usuário existente

Use essa opção para criar automaticamente uma credencial de identidade de carga de trabalho para uma identidade gerenciada atribuída pelo usuário existente. Você precisa ter uma identidade gerenciada atribuída ao usuário antes de começar.

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 e Avançar.

   

3. Selecione Identidade gerida.

   

4. Na Etapa 1: Detalhes de identidade gerenciados:

   1. Selecione Subscrição para Identidade Gerida. Esta é a assinatura do Azure que contém sua identidade gerenciada.
   2. Selecione Grupo de recursos para Identidade gerenciada. Este é o grupo de recursos que contém sua identidade gerenciada.
   3. Selecione Identidade gerenciada. Essa é a identidade gerenciada dentro do seu grupo de recursos que você usará para acessar recursos.

5. Na Etapa 2: Escopo do Azure:

   1. Selecione o Nível de escopo. Selecione Assinatura, Grupo de Gerenciamento ou Espaço de Trabalho de Aprendizado de Máquina. Os grupos de gerenciamento são contêineres que ajudam a gerenciar o acesso, a política e a conformidade em várias assinaturas. Um Espaço de Trabalho de Aprendizado de Máquina é o local para criar artefatos de aprendizado de máquina.

      • Para o escopo Assinatura, insira os seguintes parâmetros:

        Parâmetro	Description
        Subscrição para ligação ao serviço	Obrigatório. Selecione o nome da assinatura do Azure que sua identidade gerenciada acessará.
        Grupo de recursos para conexão de serviço	Opcional. Enter para limitar o acesso de identidade gerenciada a um grupo de recursos.

      • Para o escopo do Grupo de Gerenciamento, insira os seguintes parâmetros:

        Parâmetro	Description
        Grupo de Gestão	Obrigatório. Selecione o grupo de gerenciamento do Azure.

      • Para o escopo do Espaço de Trabalho de Aprendizado de Máquina , insira os seguintes parâmetros:

        Parâmetro	Description
        Subscrição	Obrigatório. Selecione o nome da assinatura do Azure.
        Grupo de recursos para conexão de serviço	Opcional. Selecione o grupo de recursos que contém o espaço de trabalho.
        Espaço de trabalho ML Espaço de trabalho	Obrigatório. Insira o nome do espaço de trabalho existente do Azure Machine Learning.

   2. Na seção Etapa 3: Detalhes da conexão de serviço: , insira ou selecione os seguintes parâmetros:

      Parâmetro	Description
      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.
      Referência de gerenciamento de serviços	Opcional. Informações de contexto de um banco de dados ITSM.
      Descrição	Opcional. Insira uma descrição da conexão de serviço.

   3. Na seção Segurança, selecione Conceder permissão de acesso a todos os pipelines para permitir que todos os pipelines usem essa conexão de serviço. Se você não selecionar essa opção, deverá conceder manualmente acesso a cada pipeline que usa essa conexão de serviço.

   4. Selecione Salvar para validar e criar a conexão de serviço.

Converter uma conexão de serviço existente para usar a federação de identidades 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 um segredo. 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.

   

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

   

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 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.

Ao converter conexões de serviço para usar a federação de identidades de carga de trabalho, você será solicitado a confirmar a atualização para cada conexão que ainda não a está usando. Após a confirmação, o script atualiza essas conexões de serviço por meio da API REST do Azure DevOps para utilizar 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 .ps1 arquivo 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 de serviço existente que usa um segredo

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 >.

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

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

   

4. Selecione Reverter novamente para confirmar sua escolha.

Ajuda e suporte

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