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. As opções recomendadas são usar a federação de identidades de carga de trabalho com um registro de aplicativo ou identidade gerenciada.

As opções de conexão de serviço recomendadas do Azure Resource Manager são:

• Registro de aplicativo (automático) com uma federação de identidade de carga de trabalho ou um segredo
• 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.

Há outras opções de autenticação de conexão de serviço do Azure Resource Manager que não estão incluídas neste artigo:

• Registro de aplicativo ou identidade gerenciada (manual) com federação de identidade de carga de trabalho ou um segredo
• Identidade gerenciada atribuída ao agente (não recomendada)
• Publicar perfil (não recomendado)

Criar um registro de aplicativo do Azure Resource Manager (automático)

Ao criar uma conexão de serviço do Azure Resource Manager, você escolherá entre dois tipos de credenciais diferentes - federação de identidade de carga de trabalho ou um segredo.

Criar um registro de aplicativo do Azure Resource Manager 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.

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.

Criar um registro de aplicativo do Azure Resource Manager com um segredo (automático)

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 um segredo para autenticação.

Aviso

Usar um segredo requer rotação e gerenciamento manual e não é recomendado. A federação de identidades de carga de trabalho é o tipo de credencial preferencial.

Você pode usar 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 aos ambientes do Azure US Government .
• Você não está se conectando do Azure DevOps Server 2019 ou de versões anteriores do Team Foundation Server.

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 do aplicativo (automático) com a credencial Secret.

   

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	Obrigatório. 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.

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.

Criar uma conexão de serviço do Azure Resource Manager para uma identidade gerenciada atribuída pelo 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 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 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 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.

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 existente do Serviço Azure Resource Manager 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 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.

   

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.