Usar tokens de acesso pessoal

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

Um PAT (Token de Acesso Pessoal) serve como uma senha alternativa para autenticação no Azure DevOps. Este PAT identifica você e determina sua acessibilidade e escopo de acesso. Portanto, trate os PATs com o mesmo nível de cuidado que as senhas.

Quando você usa ferramentas da Microsoft, sua MSA (conta Microsoft) ou ID do Microsoft Entra é um método reconhecido e com suporte. Se você usar ferramentas que não sejam da Microsoft que não dão suporte a contas da Microsoft ou do Microsoft Entra ou se preferir não compartilhar suas credenciais principais com essas ferramentas, os PATs são uma alternativa adequada.

Este artigo orienta você na criação, uso, modificação e revogação de PATs para Azure DevOps.

Você pode gerenciar PATs usando os seguintes métodos:

• Interface do usuário: por meio das configurações do usuário, conforme detalhado neste artigo
• API de gerenciamento do ciclo de vida do PAT

Para estabelecer PATs para ferramentas que não são da Microsoft, você pode usar gerenciadores de credenciais Git ou gerá-los manualmente. Recomendamos revisar nossas diretrizes de autenticação para escolher o mecanismo de autenticação apropriado. Os PATs fornecem uma alternativa direta para projetos menores que não exigem uma solução extensa. Sem um gerenciador de credenciais, os usuários inserem suas credenciais todas as vezes.

Pré-requisitos

• Permissões:
  • Ter permissão para acessar e modificar suas configurações de usuário em que os PATs são gerenciados.
    • Verificar permissões: para verificar suas permissões, execute um dos seguintes processos no Azure DevOps:
      • Vá para o seu perfil e selecione Configurações>do usuário Tokens de acesso pessoal. Se você puder ver e gerenciar seus PATs aqui, terá as permissões necessárias.
      • Vá para o seu projeto e selecione Configurações do> projeto Permissões. Encontre sua conta de usuário na lista e verifique as permissões atribuídas a você. Procure permissões relacionadas ao gerenciamento de tokens ou configurações do usuário.
  • Se sua organização tiver políticas em vigor, um administrador do Azure DevOps poderá precisar conceder permissões específicas ou adicioná-lo a uma lista de permissões para criar e gerenciar PATs.
  • Dependendo das tarefas que você deseja executar com o PAT, talvez você precise de permissões adicionais. Por exemplo:
    • Construir: Ler & Executar
    • Código: Ler, escrever e gerenciar
    • Ambiente: Ler e gerenciar
    • Projeto e equipe: leia, escreva e gerencie
    • Grupos de variáveis: Ler e criar
• Níveis de acesso: ter pelo menos acesso básico.
• Práticas recomendadas de segurança: Familiarize-se com as práticas recomendadas de segurança para gerenciar PATs, como usá-los somente quando necessário e alterná-los regularmente.

Criar um PAT

1. Entre em sua organização (https://dev.azure.com/{Your_Organization}).

2. Na sua página inicial, abra as configurações do usuário e selecione Tokens de acesso pessoal.

   

3. Selecione + New Token.

   

4. Nomeie seu token, selecione a organização em que deseja usar o token e defina seu token para expirar automaticamente após um determinado número de dias.

   

5. Selecione os escopos desse token para autorizar suas tarefas específicas.

   Por exemplo, para criar um token para um agente de build e versão para autenticar no Azure DevOps, defina o escopo do token como Pools de Agentes (Ler e gerenciar). Para ler eventos de log de auditoria e gerenciar ou excluir fluxos, selecione Ler Log de Auditoria e, em seguida, selecione Criar.

   

   Observação

   Você pode ser impedido de criar PATs de escopo completo. Nesse caso, o administrador do Azure DevOps na ID do Microsoft Entra habilitou uma política que limita você a um conjunto específico de escopos definidos de forma personalizada. Para obter mais informações, consulte Gerenciar PATs com políticas/Restringir a criação de PATs com escopo completo. Para um PAT personalizado, o escopo necessário para acessar a API de Governança de Componentes, vso.governance, não é selecionável na interface do usuário.

6. Quando terminar, copie o token e armazene-o em um local seguro. Para sua segurança, ele não é exibido novamente.

   

Use seu PAT em qualquer lugar em que suas credenciais de usuário sejam necessárias para autenticação no Azure DevOps.

Notificações

Durante a vida útil de um PAT, os usuários recebem duas notificações: a primeira no momento da criação e a segunda sete dias antes de sua expiração.

Depois de criar um PAT, você receberá uma notificação semelhante ao exemplo a seguir. Essa notificação serve como confirmação de que seu PAT foi adicionado com êxito à sua organização.

A imagem a seguir mostra um exemplo da notificação de sete dias antes que o PAT expire.

Notificação inesperada

Se você receber uma notificação inesperada do PAT, isso pode significar que um administrador ou ferramenta criou um PAT para você. Aqui estão alguns exemplos.

• Um token chamado "git: https://dev.azure.com/{Your_Organization} on YourMachine" é criado quando você se conecta a um repositório Git do Azure DevOps por meio de git.exe.
• Um token chamado "Ganchos de Serviço: : Serviço de Aplicativo do Azure: : Implantar aplicativo Web" é criado quando você ou um administrador configura uma implantação de aplicativo Web do Serviço de Aplicativo do Azure.
• Um token chamado "WebAppLoadTestCDIntToken" é criado quando o teste de carga da Web é configurado como parte de um pipeline por você ou por um administrador.
• Um token chamado "Integração do Microsoft Teams" é criado quando uma Extensão de Mensagens de Integração do Microsoft Teams é configurada.

Use um PAT

Seu PAT serve como sua identidade digital, como uma senha.

Git

As interações do Git exigem um nome de usuário, que pode ser qualquer coisa, exceto uma string vazia. Para usar um PAT com autenticação básica HTTP, Base64-encode você $MyPat é mostrado no bloco de código a seguir.

$MyPat = 'yourPat'
$headerValue = "Authorization: Basic " + [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(":" + $MyPat))
$env:GIT_AUTH_HEADER = $headerValue

git --config-env=http.extraheader=GIT_AUTH_HEADER clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName

MY_PAT=yourPAT # replace "yourPAT" with "PatStringFromWebUI"
export HEADER_VALUE=$(echo -n "Authorization: Basic "$(printf ":%s" "$MY_PAT" | base64))

git --config-env=http.extraheader=HEADER_VALUE clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName

Repositórios existentes

• Remover origem existente: Se você adicionou anteriormente a origem usando um nome de usuário, remova-a executando o seguinte comando:

  git remote remove origin

• Autenticar com um PAT: Se você encontrar problemas com a autenticação padrão, execute o seguinte comando para autenticar por meio da linha de comando:

  git remote add origin https://dev.azure.com/<PAT>@<company_machineName>:/<project-name>/_git/<repo_name>

  git push -u origin --all

  Refere-se path to git repo = /_git/do à estrutura de caminho de URL usada em Azure DevOps para repositórios Git. O /_git/ segmento indica que você está acessando um repositório Git e deve ser substituído do pelo nome real do repositório. Por exemplo, se o seu repositório for nomeado my-repo, o caminho será '/_git/my-repo'.

• Clonar repositório: se você estiver usando o Git e precisar se autenticar, execute o seguinte comando:

  git clone https://{organization}@dev.azure.com/{organization}/_git/{repository}

  Substitua {organization} pelo nome da organização do Azure DevOps e {repository} pelo nome do repositório.

Usar um PAT em seu código

Você pode usar um PAT em seu código para autenticar solicitações de API e automatizar fluxos de trabalho. Para fazer isso, inclua o PAT no cabeçalho de autorização de suas solicitações HTTP.

Authorization: Basic BASE64_USERNAME_PAT_STRING

public static async void GetBuilds()
{
    try
    {
        var personalaccesstoken = "PATFROMWEB";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(
                new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
                Convert.ToBase64String(
                    System.Text.ASCIIEncoding.ASCII.GetBytes(
                        string.Format("{0}:{1}", "", personalaccesstoken))));

            using (HttpResponseMessage response = client.GetAsync(
                        "https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.0").Result)
            {
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
    }
}

public static async void GetBuilds()
{
   try
  {
      var personalaccesstoken = "PATFROMWEB";

      using (HttpClient client = new HttpClient())
       {
           client.DefaultRequestHeaders.Accept.Add(
              new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

           client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
               Convert.ToBase64String(
                   System.Text.ASCIIEncoding.ASCII.GetBytes(
                       string.Format("{0}:{1}", "", personalaccesstoken))));

          using (HttpResponseMessage response = client.GetAsync(
                       $"https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.0").Result)
           {
               response.EnsureSuccessStatusCode();
               string responseBody = await response.Content.ReadAsStringAsync();
               Console.WriteLine(responseBody);
           }
       }
   }
   catch (Exception ex)
   {
       Console.WriteLine(ex.ToString());
   }
}

curl -u :{PAT} https://dev.azure.com/{organization}/_apis/build-release/builds

Quando seu código está funcionando, é um bom momento para mudar da autenticação básica para o OAuth.

Para obter mais informações e exemplos de como usar PATs, consulte os seguintes artigos:

• Configurar gerenciadores de credenciais do Git
• Acessar APIs REST
• Usar o NuGet em um Mac
• Autenticar clientes de relatórios
• Introdução à CLI do Azure DevOps

Alterações no formato

A partir de julho de 2024, alteramos significativamente o formato dos PATs emitidos pelo Azure DevOps. Essas alterações fornecem mais benefícios de segurança e melhoram as ferramentas de detecção de segredos disponíveis por meio de nossas ofertas de parceiros, como GitHub Advanced Security para Azure DevOps. Esse novo formato PAT segue o formato recomendado em todos os produtos da Microsoft. A inclusão de bits mais identificáveis melhora a taxa de detecção de falsos positivos dessas ferramentas secretas de detecção e nos permite mitigar os vazamentos detectados mais rapidamente.

Principais mudanças:

• Aumento do comprimento do token: Os novos tokens agora têm 84 caracteres, com 52 caracteres sendo dados aleatórios. Esse comprimento aumentado melhora a entropia geral, tornando os tokens mais resistentes a possíveis ataques de força bruta.
• Assinatura fixa: Os tokens emitidos pelo nosso serviço incluem uma assinatura fixa AZDO nas posições 76-80.

Ação necessária:

• Regenerar PATs existentes: é altamente recomendável regenerar todos os PATs atualmente em uso para aproveitar esses aprimoramentos de segurança.
• Suporte ao integrador: os integradores devem atualizar seus sistemas para acomodar os comprimentos de token novos e existentes.

Artigos relacionados

• Saiba mais sobre segurança, autenticação e autorização
• Examinar as permissões e o acesso padrão para o Azure DevOps
• Revogar PATs de usuário (para administradores)
• Gerenciar entidades de serviço e identidades gerenciadas no Azure DevOps