Usar tokens de acesso pessoal

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019 | TFS 2018

Você pode usar um PAT (token de acesso pessoal) como uma senha alternativa para autenticar no Azure DevOps. Neste artigo, mostramos como criar, usar, modificar e revogar PATs para o Azure DevOps.

Sobre PATs

Um token de acesso pessoal contém suas credenciais de segurança para o Azure DevOps. Um PAT identifica você, suas organizações acessíveis e os escopos de acesso. Dessa forma, eles são tão críticos quanto as senhas, portanto, você deve tratá-las da mesma maneira.

Se você estiver trabalhando em ferramentas da Microsoft, sua MSA (conta Microsoft) ou o Azure AD (Azure Active Directory) será uma abordagem aceitável e compatível. Mas, se você estiver trabalhando com ferramentas de terceiros que não dão suporte a contas Microsoft ou Azure AD – ou não desejar fornecer suas principais credenciais para a ferramenta – use PATs para limitar seu risco.

Você pode criar e gerenciar seus PATs de uma das seguintes formas:

Para configurar PATs para ferramentas não Microsoft, use gerentes de credenciais do Git ou crie-os manualmente. Recomendamos que você examine nossas diretrizes de autenticação para ajudá-lo a escolher o mecanismo de autenticação correto. Para projetos menores que exigem uma solução menos robusta, os PATs são uma alternativa simples. A menos que os usuários estejam usando um gerenciador de credenciais, eles precisam inserir suas credenciais sempre.

Criar um PAT

Observação

As imagens que você vê no portal da Web podem ser diferentes das imagens que você vê neste artigo. Essas diferenças resultam de atualizações feitas no Azure DevOps ou recursos de visualização habilitados. Habilitamos o recurso nova página do gerenciador de contas . A funcionalidade básica disponível para você permanece a mesma, a menos que seja explicitamente mencionada.

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

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

    Captura de tela mostrando a seleção, Tokens de Acesso Pessoal.

  3. Selecione + New Token.

    Captura de tela mostrando a seleção, Novo Token.

  4. Nomeie seu token, selecione a organização na qual você deseja usar o token e defina seu token para expirar automaticamente após um número definido de dias.

    Captura de tela mostrando a entrada de informações básicas do token.

  5. Selecione os escopos desse token a serem autorizados para suas tarefas específicas.

    Por exemplo, para criar um token para permitir que um agente de build e lançamento se autentique em Azure DevOps Services, limite o escopo do token para Pools de Agentes (Gerenciamento de leitura&). Para ler eventos de log de auditoria e gerenciar e excluir fluxos, selecione Ler Log de Auditoria e, em seguida, selecione Criar.

    Captura de tela mostrando escopos selecionados para um PAT.

    Observação

    Você pode ser impedido de criar PATs de escopo completo. Nesse caso, o Administrador do Azure DevOps no Azure AD habilitou uma política que limita você a um conjunto específico de escopos definidos personalizados. Para obter mais informações, consulte Gerenciar PATs com políticas/Restringir a criação de PATs com escopo completo. Para um PAT definido 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, ela não será mostrada novamente.

    Captura de tela mostrando como copiar o token para sua área de transferência.

Aviso

Trate e use um PAT como sua senha e mantenha-o em segredo.

  1. Entre no portal da Web (https://{server}:8080/tfs/).

  2. Na home page, abra seu perfil. Acesse seus detalhes de segurança.

    Captura de tela mostrando a home page, abrindo seu perfil e o botão Segurança.

  3. Criar um token de acesso pessoal.

    Captura de tela mostrando a adição de um token de acesso pessoal.

  4. Nomeie seu token. Selecione um tempo de vida para o token.

    Se você tiver mais de uma organização, também poderá selecionar a organização na qual deseja usar o token.

    Captura de tela mostrando a entrada de informações, incluindo o nome do token e o tempo de vida.

  5. Selecione os escopos desse token a serem autorizados para suas tarefas específicas.

    Por exemplo, para criar um token para habilitar a autenticação de um agente de build e lançamento , limite o escopo do token para Pools de Agentes (leitura, gerenciamento).

  6. Quando terminar, copie o token. Para sua segurança, ela não será mostrada novamente. Use esse token como sua senha. Selecione Fechar.

    Captura de tela mostrando o token criado.

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

Importante

Para organizações apoiadas pelo Azure Active Directory, você tem 90 dias para entrar com seu novo PAT, caso contrário, ele é considerado inativo. Para obter mais informações, consulte Frequência de entrada do usuário para acesso condicional.

Notificações

Os usuários recebem duas notificações durante o tempo de vida de um PAT – uma após a criação e outra sete dias antes da expiração.

Depois de criar um PAT, você receberá uma notificação semelhante ao exemplo a seguir. Essa notificação confirma que seu PAT foi adicionado à 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 de seu PAT expirar.

Captura de tela mostrando a notificação de pat perto da expiração.

Notificação inesperada

Se você receber uma notificação pat inesperada, um administrador ou ferramenta poderá ter criado um PAT em seu nome. Consulte os exemplos a seguir.

  • Quando você se conecta a um repositório Git do Azure DevOps por meio de git.exe. ele cria um token com um nome de exibição como "git: https://MyOrganization.visualstudio.com/ em MyMachine".
  • Quando você ou um administrador configura um Serviço de Aplicativo do Azure implantação de aplicativo Web, ele cria um token com um nome de exibição como "Ganchos de Serviço: : Serviço de Aplicativo do Azure: : Implantar aplicativo Web".
  • Quando você ou um administrador configura o teste de carga da Web como parte de um pipeline, ele cria um token com um nome de exibição como "WebAppLoadTestCDIntToken".
  • Quando um Microsoft Extensão de Mensagens de Integração do Teams é configurado, ele cria um token com um nome de exibição como "Microsoft Integração do Teams".

Aviso

Se você acredita que um PAT existe por erro, sugerimos que você revogue o PAT. Em seguida, altere sua senha. Como um usuário Azure AD, verifique com o administrador se sua organização foi usada de uma origem ou localização desconhecida. Confira também as perguntas frequentes sobre a verificação acidental em um PAT em um repositório público do GitHub.

Usar um PAT

Seu PAT é sua identidade e representa você quando você a usa, assim como uma senha.

Git

As interações do Git exigem um nome de usuário, que pode ser qualquer coisa, exceto a cadeia de caracteres vazia. Para usar um PAT com autenticação básica HTTP, use Base64-encode para e $MyPat, que está incluído no bloco de código a seguir.

No PowerShell, insira o código a seguir.

$MyPat = 'yourPAT'

$B64Pat = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("`:$MyPat"))

git -c http.extraHeader="Authorization: Basic $B64Pat" 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. O Git para Windows é necessário.

Repositórios existentes

Para repositórios existentes, se você já adicionou a origem usando o nome de usuário, execute o comando a seguir primeiro.

git remote remove origin

Caso contrário, execute o comando a seguir.

git remote add origin https://<PAT>@<company_machineName>.visualstudio.com:/<path-to-git-repo> path to git repo = <project name>/_git/<repo_name> git push -u origin --all

Usar um PAT em seu código

Você pode usar um PAT em seu código.

Se você quiser fornecer o PAT por meio de um cabeçalho HTTP, primeiro converta-o em uma cadeia de caracteres Base64. O exemplo a seguir mostra como converter em Base64 usando 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

Ao usar variáveis, adicione um $ no início da cadeia de caracteres, 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());
   }
}

Quando o 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:

Se você habilitar a Autenticação Básica do IIS para TFS, os PATs não serão válidos. Para obter mais informações, consulte Usando a Autenticação Básica do IIS com o TFS local.

Modificar um PAT

Você pode regenerar ou estender um PAT e modificar seu escopo. Após a regeneração, o PAT anterior não é mais autorizado.

  1. Na home page, abra as configurações do usuário e selecione Perfil.

    Captura de tela mostrando a sequência de botões a serem selecionados para modificar um PAT.

  2. Em Segurança, selecione Tokens de acesso pessoal. Selecione o token que você deseja modificar e Editar.

    Captura de tela mostrando o botão Editar realçado para modificar o PAT.

  3. Edite o nome do token, a organização à qual ele se aplica, a expiração do token ou o escopo de acesso associado ao token e selecione Salvar.

    Captura de tela mostrando o PAT salvo.

Revogar um PAT

Você pode revogar um PAT a qualquer momento, por vários motivos.

  1. Na home page, abra as configurações do usuário e selecione Perfil.

    Captura de tela mostrando a sequência de botões a serem selecionados, o Team Services, a página Visualizar e revogar um PAT.

  2. Em Segurança, selecione Tokens de acesso pessoal. Selecione o token para o qual você deseja revogar o acesso e, em seguida, selecione Revogar.

    Captura de tela mostrando a seleção para revogar um único token ou todos os tokens.

  3. Selecione Revogar na caixa de diálogo de confirmação.

    Captura de tela mostrando a tela de confirmação para revogar o PAT.

Perguntas frequentes

P: O que acontecerá com um PAT se uma conta de usuário estiver desabilitada?

R: Depois que um usuário é removido do Azure DevOps, o PAT é invalidado dentro de 1 hora. Se sua organização estiver conectada ao Azure Active Directory (Azure AD), o PAT também será invalidado em Azure AD, pois pertence ao usuário. Recomendamos que o usuário gire seu PAT para outro usuário ou conta de serviço para manter os serviços em execução.

P: Há 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 nossas 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 organizações e perfis dão suporte apenas ao OAuth. Para obter mais informações, consulte Gerenciar PATs usando a API REST.

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

R: O Azure DevOps verifica se há PATs verificados em repositórios públicos no GitHub. Quando encontramos um token vazado, enviamos imediatamente uma notificação por email detalhada ao proprietário do token e registramos um evento no log de auditoria da sua organização do Azure DevOps. Incentivamos os usuários afetados a atenuar imediatamente girando ou revogando o PAT vazado.

Há uma política para gerenciar PATs vazados! 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 dá suporte à passagem 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. Consulte os seguintes exemplos para obter mais detalhes: dotnet,NuGet.exe. Se você quiser publicar seus pacotes usando o Azure Pipelines, use a tarefa Autenticação do NuGet para autenticar com o exemplo de feed.