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

Observação

Estamos lançando 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 antigo.

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, assim como um aplicativo do Serviço de Aplicativo do Azure, sem precisar se autenticar todas as vezes.

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 identidade 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
• A 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. Use essa opção quando não tiver permissão para criar um registro de aplicativo.

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 pelo agente (não recomendado)
• 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 diferentes de credenciais: federação de identidade de carga de trabalho ou um segredo.

Criar um registro de aplicativo do Azure Resource Manager com a federação de identidade de carga de trabalho (automática)

Você pode 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 ambiente do Azure Stack nem do Azure US Government.
• Todas as tarefas de extensões do Marketplace que você usa foram atualizadas para oferecer suporte à federação de identidade de carga de trabalho.

Com essa seleção, o Azure DevOps consulta automaticamente a assinatura, o grupo de gerenciamento ou o workspace do Machine Learning 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, acesse Configurações do projeto>Conexões de serviço.

   Para saber mais, confira Abra as configurações do projeto.

2. Selecione Nova conexão de serviço, Azure Resource Manager e Avançar.

   

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

   

4. Selecione um Nível de escopo. Selecione Assinatura, Grupo de Gerenciamento ou Workspace do Machine Learning. 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. O workspace do Machine Learning é um local para criar artefatos de Machine Learning.

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

     Parâmetro	Descrição
     Assinatura	Obrigatória. 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 Workspace do Machine Learning, insira os seguintes parâmetros:

     Parâmetro	Descrição
     Assinatura	Obrigatória. Selecione a Assinatura do Azure.
     Grupo de Recursos	Obrigatória. Selecione o grupo de recursos que contém o workspace.
     Workspace do Machine Learning	Obrigatória. Selecione o workspace do Azure Machine Learning.

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

6. Você também pode inserir 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 acesso manualmente a cada pipeline que usa essa conexão de serviço.

8. Selecione Salvar.

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.

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 Workspace do Machine Learning ao qual você deseja se conectar e cria um segredo para autenticação.

Aviso

O uso de um segredo requer rotação e gerenciamento manuais e não é recomendado. A federação de identidade de carga de trabalho é o tipo de credencial preferencial.

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

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

2. Selecione Nova conexão de serviço, Azure Resource Manager e Avançar.

   

3. Selecione Registro de aplicativo (automático) com a credencial Segredo.

   

4. Selecione um Nível de escopo. Selecione Assinatura, Grupo de Gerenciamento ou Workspace do Machine Learning. 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. O workspace do Machine Learning é um local para criar artefatos de Machine Learning.

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

     Parâmetro	Descrição
     Assinatura	Obrigatória. Selecione a Assinatura do Azure.
     Grupo de recursos	Obrigatória. 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 Workspace do Machine Learning, insira os seguintes parâmetros:

     Parâmetro	Descrição
     Assinatura	Obrigatória. Selecione a Assinatura do Azure.
     Grupo de Recursos	Obrigatória. Selecione o grupo de recursos que contém o workspace.
     Workspace do Machine Learning	Obrigatória. Selecione o workspace do Azure Machine Learning.

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

6. Você também pode inserir 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 acesso manualmente a cada pipeline que usa essa conexão de serviço.

8. Selecione Salvar.

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.

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 pelo usuário existente antes de começar.

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

2. Selecione Nova conexão de serviço, Azure Resource Manager e Avançar.

   

3. Selecione Identidade gerenciada.

   

4. Na Etapa 1: detalhes da identidade gerenciada:

   1. Selecione Assinatura para Identidade Gerenciada. Essa é a assinatura do Azure que contém sua identidade gerenciada.
   2. Selecione Grupo de recursos para Identidade Gerenciada. Esse é o grupo de recursos que contém sua identidade gerenciada.
   3. Selecione Identidade Gerenciada. Essa é a identidade gerenciada dentro do 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 Workspace do Machine Learning. 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. O workspace do Machine Learning é um local para criar artefatos de Machine Learning.

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

        Parâmetro	Descrição
        Assinatura para conexão de serviço	Obrigatória. Selecione o nome da assinatura do Azure que sua identidade gerenciada acessará.
        Grupo de recursos para conexão de serviço	Opcional. Insira para limitar o acesso à identidade gerenciada a um grupo de recursos.

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

        Parâmetro	Descrição
        Grupo de gerenciamento	Obrigatória. Selecione o grupo de gerenciamento do Azure.

      • Para o escopo do Workspace do Machine Learning, insira os seguintes parâmetros:

        Parâmetro	Descrição
        Assinatura	Obrigatória. 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 workspace.
        Espaço de trabalho do ML Workspace	Obrigatória. Insira o nome do workspace existente do Azure Machine Learning.

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

      Parâmetro	Descrição
      Nome da conexão de serviç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.
      Referência do 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 acesso manualmente a cada pipeline que usa essa conexão de serviço.

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

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 existente do Azure Resource Manager para usar a federação de identidade da carga de trabalho para autenticação em vez de um segredo. 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:

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

2. Selecione a conexão de serviço que você quer converter para usar a identidade do workload.

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

Ao converter conexões de serviço para usar a federação de identidade de carga de trabalho, você é solicitado a confirmar a atualização para cada conexão que ainda não a esteja 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 identidade de carga de trabalho.

O script requer o PowerShell 7.3 ou posterior 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 Azure Resource Manager Service 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 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:

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

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