Usar tokens de acesso pessoal

Artigo
10/18/2024

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 artigo orienta você na criação, uso, modificação e revogação de PATs para Azure DevOps.

Sobre PATs

Use um PAT como suas credenciais de segurança para o 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.

Crie e gerencie 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.

Criar um PAT

Entre em sua organização (https://dev.azure.com/{Your_Organization}).
Na sua página inicial, abra as configurações do usuário e selecione Tokens de acesso pessoal.
Selecione + New Token.
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.
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.
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.

Importante

Trate um PAT com o mesmo cuidado que sua senha e mantenha-o confidencial.
Entre com seu novo PAT dentro de 90 dias para organizações com suporte da ID do Microsoft Entra; caso contrário, o PAT se torna inativo. Para obter mais informações, consulte Frequência de entrada do usuário para Acesso Condicional.

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.

Captura de tela mostrando a notificação criada pelo PAT.

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

Captura de tela mostrando a notificação de expiração do PAT.

Para obter mais informações, consulte Configurar um servidor SMTP e personalizar o email para alertas e solicitações de feedback.

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.

Aviso

Revogue o PAT se suspeitar que ele existe por engano. Siga as etapas para revogar o PAT e alterar sua senha.
Verifique com o administrador se você é um usuário do Microsoft Entra para ver se sua organização foi acessada por uma fonte ou local desconhecido.
Examine as perguntas frequentes sobre check-ins acidentais do PAT em repositórios públicos do GitHub.

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.

Windows
Linux/macOS

No PowerShell, insira o 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

Use gerenciadores de credenciais para evitar inserir suas credenciais todas as vezes e manter seu token mais seguro:

Use o Gerenciador de Credenciais do Git.
Instale o Git for Windows.

No Bash, insira o código a seguir.

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

Para manter seu token mais seguro, use os gerentes de credenciais para que você não precise inserir suas credenciais todas as vezes. Recomendamos o Git Credential Manager.

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.

Windows
Linux/macOS

Para fornecer o PAT por meio de um cabeçalho HTTP, primeiro converta-o em uma Base64 cadeia de caracteres. O exemplo a seguir mostra como converter para Base64 usar C#.


Authorization: Basic BASE64_USERNAME_PAT_STRING

A cadeia de caracteres resultante pode ser fornecida como um cabeçalho HTTP no formato a seguir.

O exemplo a seguir usa a classe HttpClient em C#.

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());
    }
}

Dica

Quando você estiver usando variáveis, adicione um $ no início da string, como no exemplo a seguir.

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());
   }
}

O exemplo a seguir obtém uma lista de builds usando curl.


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:

Modificar um PAT

Siga os seguintes passos para:

Regenere um PAT para criar um novo token, o que invalida o anterior.
Estenda um PAT para aumentar seu período de validade.
Altere o escopo de um PAT para alterar suas permissões.

Na página inicial, abra as configurações do usuário e selecione Perfil.
Em Segurança, selecione Tokens de acesso pessoal. Selecione o token que você deseja modificar e, em seguida , Editar.
Edite o nome do token, a expiração do token ou o escopo de acesso associado ao token e selecione Salvar.

Revogar um PAT

Você pode revogar um PAT a qualquer momento por estes e outros motivos:

Revogue um PAT se suspeitar que ele está comprometido.
Revogue um PAT quando ele não for mais necessário.
Revogue um PAT para impor políticas de segurança ou requisitos de conformidade.

Na página inicial, abra as configurações do usuário e selecione Perfil.
Em Segurança, selecione Tokens de acesso pessoal. Selecione o token para o qual você deseja revogar o acesso e, em seguida, selecione Revogar.
Selecione Revogar na caixa de diálogo de confirmação.

Para obter mais informações, consulte Revogar PATs de usuário para administradores.

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.

Importante

Ambos os formatos permanecem válidos no futuro próximo, mas incentivamos ativamente os clientes a fazer a transição para o novo formato de 84 caracteres. À medida que a adoção do novo formato aumenta, consideramos desativar o formato mais antigo de 52 caracteres e todos os tokens emitidos nesse estilo.

Perguntas Frequentes

P: Por que não posso editar ou regenerar um PAT com escopo para uma única organização?

R: Verifique se você está conectado à organização em que seu PAT está no escopo. Você pode exibir todos os seus PATs enquanto estiver conectado a qualquer organização na mesma ID do Microsoft Entra, mas só poderá editar tokens no escopo da organização quando estiver conectado à organização para a qual eles estão no escopo.

P: O que acontece com um PAT se uma conta de usuário for desativada?

R: Quando um usuário é removido do Azure DevOps, o PAT é invalidado em 1 hora. Se sua organização estiver conectada à ID do Microsoft Entra, o PAT também será invalidado na ID do Microsoft Entra, pois ela pertence ao usuário. Recomendamos alternar o PAT para outro usuário ou conta de serviço para manter os serviços em execução.

P: Existe uma maneira de renovar um PAT por meio da API REST?

R: Sim, há uma maneira de renovar, gerenciar e criar PATs usando nossas APIs de gerenciamento do ciclo de vida do PAT. Para obter mais informações, consulte Gerenciar PATs usando a API REST e perguntas frequentes.

P: Posso usar a autenticação básica com todas as APIs REST do Azure DevOps?

R: Não. Você pode usar a autenticação básica com a maioria das APIs REST do Azure DevOps, mas as organizações e os perfis só dão suporte ao OAuth. Para obter mais informações, consulte Gerenciar PATs usando a API REST.

P: O que acontece se eu acidentalmente verificar meu PAT em um repositório público no GitHub?

R: O Azure DevOps verifica PATs com check-in de repositórios públicos no GitHub. Quando encontramos um token vazado, enviamos imediatamente uma notificação detalhada por email ao proprietário do token e registramos um evento no log de auditoria da organização do Azure DevOps. A menos que você tenha desabilitado a política Revogar automaticamente tokens de acesso pessoal vazados, revogamos imediatamente o PAT vazado. Incentivamos os usuários afetados a mitigar o problema revogando o token vazado e substituindo-o por um novo token.

Para obter mais informações, consulte Revogar PATs vazados automaticamente.

P: Posso usar um token de acesso pessoal como uma ApiKey para publicar pacotes NuGet em um feed do Azure Artifacts usando a linha de comando dotnet/nuget.exe?

R: Não. O Azure Artifacts não tem suporte para a transmissão de um token de acesso pessoal como uma ApiKey. Ao usar um ambiente de desenvolvimento local, recomendamos instalar o Provedor de Credenciais do Azure Artifacts para autenticar com o Azure Artifacts. Para obter mais informações, consulte os seguintes exemplos: dotnet e NuGet.exe. Se você quiser publicar seus pacotes usando o Azure Pipelines, use a tarefa Autenticar do NuGet para autenticar com o exemplo de feed.

P: Por que meu PAT parou de funcionar?

R: A autenticação PAT exige que você entre regularmente no Azure DevOps usando o fluxo de autenticação completo. Entrar uma vez a cada 30 dias é suficiente para muitos usuários, mas talvez seja necessário entrar com mais frequência, dependendo da configuração do Microsoft Entra. Se o PAT parar de funcionar, primeiro tente entrar na sua organização e preencha o prompt de autenticação completo. Se o seu PAT ainda não funcionar, verifique se ele expirou.

P: Como faço para criar chaves de acesso que não estejam vinculadas a uma pessoa específica para fins de implantação?

R: No Azure DevOps, você pode criar chaves de acesso que não estão vinculadas a uma pessoa específica usando Entidades de Serviço ou Gerenciar Identidades. Para obter mais informações, consulte Gerenciar conexões de serviço, Usar segredos do Azure Key Vault no Azure Pipelines.

Compartilhar via

Usar tokens de acesso pessoal

Sobre PATs

Criar um PAT

Notificações

Notificação inesperada

Use um PAT

Repositórios existentes

Usar um PAT em seu código

Modificar um PAT

Revogar um PAT

Alterações no formato

Perguntas Frequentes

P: Por que não posso editar ou regenerar um PAT com escopo para uma única organização?

P: O que acontece com um PAT se uma conta de usuário for desativada?

P: Existe uma maneira de renovar um PAT por meio da API REST?

P: Posso usar a autenticação básica com todas as APIs REST do Azure DevOps?

P: O que acontece se eu acidentalmente verificar meu PAT em um repositório público no GitHub?

P: Posso usar um token de acesso pessoal como uma ApiKey para publicar pacotes NuGet em um feed do Azure Artifacts usando a linha de comando dotnet/nuget.exe?

P: Por que meu PAT parou de funcionar?

P: Como faço para criar chaves de acesso que não estejam vinculadas a uma pessoa específica para fins de implantação?

Comentários

Recursos adicionais

Compartilhar via

Usar tokens de acesso pessoal

Sobre PATs

Criar um PAT

Notificações

Notificação inesperada

Use um PAT

Repositórios existentes

Usar um PAT em seu código

Modificar um PAT

Revogar um PAT

Alterações no formato

Artigos relacionados

Perguntas Frequentes

P: Por que não posso editar ou regenerar um PAT com escopo para uma única organização?

P: O que acontece com um PAT se uma conta de usuário for desativada?

P: Existe uma maneira de renovar um PAT por meio da API REST?

P: Posso usar a autenticação básica com todas as APIs REST do Azure DevOps?

P: O que acontece se eu acidentalmente verificar meu PAT em um repositório público no GitHub?

P: Posso usar um token de acesso pessoal como uma ApiKey para publicar pacotes NuGet em um feed do Azure Artifacts usando a linha de comando dotnet/nuget.exe?

P: Por que meu PAT parou de funcionar?

P: Como faço para criar chaves de acesso que não estejam vinculadas a uma pessoa específica para fins de implantação?

Comentários

Recursos adicionais