Usar tokens de acesso pessoal

Azure DevOps Services | Azure DevOps Server 2020 | 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 que não são da Microsoft, use os 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 para o 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 home page, abra as configurações do usuário e selecione tokens de acesso pessoal.

    Selecionar Tokens de Acesso Pessoal

  3. Selecione + New Token.

    Selecionar Novo Token para criar

  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.

    Inserir informações básicas de 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 selecione Criar.

    Selecionar escopos para seu 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 de escopo completo. Para um PAT definido personalizado, o escopo necessário para acessar a API vso.governancede Governança de Componentes 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.

    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. Vá para seus detalhes de segurança.

    Home page, abra seu perfil, vá para Segurança

  3. Criar um token de acesso pessoal.

    Adicionar um token de acesso pessoal

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

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

    Nomeie seu token, selecione um tempo de vida útil. Se estiver usando Azure DevOps Services, selecione uma conta para o 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, limite o escopo do token para Pools de Agentes (ler, gerenciar).

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

    Usar um token como senha para suas ferramentas ou aplicativos git

Use seu PAT em qualquer lugar onde suas credenciais de usuário forem 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 a 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 outras sete dias antes da expiração.

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

Notificação criada pelo PAT

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

PAT quase notificação de 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/ on MyMachine".
  • Quando você ou um administrador configura uma implantação de aplicativo Web Serviço de Aplicativo do Azure, ele cria um token com um nome de exibição como "Service Hooks: : 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 uma Extensão de Mensagens de Integração do Microsoft Teams é configurada, ela cria um token com um nome de exibição como "Integração do Microsoft Teams".

Aviso

Se você acredita que um PAT existe no 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 local desconhecido. Consulte também as perguntas frequentes sobre a verificação acidental de 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 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á tiver adicionado 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, no entanto, observe o aviso a seguir.

Aviso

Algumas de nossas APIs públicas atualmente não estão associadas a um escopo pat e, portanto, só podem ser usadas com PATs de "escopo completo". Por isso, restringir a criação de PATs com escopo completo pode bloquear alguns fluxos de trabalho. Estamos trabalhando para identificar e documentar as APIs afetadas e, eventualmente, associá-las ao escopo apropriado. Por enquanto, esses fluxos de trabalho podem ser desbloqueados usando a lista de permissões.

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

Quando você estiver usando 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 de autenticação básica para 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 Como usar 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.

    Meu perfil Team Services, página Versão prévia, modifique um PAT.

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

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

    Modificar e salvar o PAT

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.

    Meu perfil Team Services, página Visualização, revogar um PAT.

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

    Revogar um token ou todos os tokens

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

    Confirmar revogação

Perguntas Frequentes

P: O que acontece 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 de 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 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 se há PATs verificados em repositórios públicos no GitHub. Quando encontramos um token vazado, enviamos imediatamente uma notificação de email detalhada para o 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 vazadas! 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, é recomendável instalar o Provedor de Credenciais do Azure Artifacts para autenticar com o Azure Artifacts. Confira 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 seu exemplo de feed.