Utilizar tokens de acesso pessoal

Artigo
10/25/2024

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

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

Quando utiliza ferramentas Microsoft, a sua conta Microsoft (MSA) ou ID Microsoft Entra é um método reconhecido e suportado. Se você usa ferramentas que não são da Microsoft que não oferecem suporte a contas Microsoft ou Microsoft Entra, ou se prefere 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 o Azure DevOps.

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

Interface do usuário (UI): Através das configurações do usuário, conforme detalhado neste artigo
API de Gestão do Ciclo de Vida da PAT

Para estabelecer PATs para ferramentas que não sejam da Microsoft, você pode usar gerenciadores de credenciais Git ou gerá-los manualmente. Recomendamos que reveja as nossas orientações de autenticação para escolher o mecanismo de autenticação adequado. Os PATs oferecem uma alternativa simples para projetos menores que não exigem uma solução extensa. Sem um gerenciador de credenciais, os usuários inserem suas credenciais a cada vez.

Pré-requisitos

Permissões:
- Tenha permissão para acessar e modificar suas configurações de usuário onde os PATs são gerenciados.
  - Verificar permissões: para verificar suas permissões, execute um dos seguintes processos no Azure DevOps:
    - Aceda ao seu perfil e selecione Definições de>utilizador Tokens de acesso pessoal. Se você pode ver e gerenciar seus PATs aqui, você tem 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 a sua organização tiver políticas em vigor, um Administrador de DevOps do Azure poderá ter de lhe conceder permissões específicas ou adicioná-lo a uma lista de permissões para criar e gerir PATs.
- Dependendo das tarefas que você deseja executar com o PAT, você pode precisar de permissões adicionais. Por exemplo:
  - Build: Ler & executar
  - Código: Ler, escrever, & gerenciar
  - Ambiente: Ler e gerir
  - Projeto e equipa: Ler, escrever, & gerir
  - Grupos de variáveis: Ler & 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 apenas quando necessário e alterná-los regularmente.

Criar uma PAT

Inicie sessão na 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 + Novo Token.
Nomeie seu token, selecione a organização onde você deseja usar o token e defina seu token para expirar automaticamente após um número definido de dias.
Selecione os escopos para este token a autorizar para suas tarefas específicas.

Por exemplo, para criar um token para que um agente de compilação e liberação se autentique no Azure DevOps, defina o escopo do token como Pools de Agentes (Ler & gerenciar). Para ler eventos de log de auditoria e gerenciar ou excluir fluxos, selecione Ler Log de Auditoria e selecione Criar.

Nota

Você pode ser impedido de criar PATs com escopo completo. Nesse caso, seu Administrador de DevOps do Azure na ID do Microsoft Entra habilitou uma política que limita você a um conjunto específico de escopos personalizados. 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 pode ser selecionado 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 sua PAT em qualquer lugar em que suas credenciais de usuário sejam necessárias para autenticação no Azure DevOps.

Importante

Trate uma PAT com o mesmo cuidado que a sua palavra-passe e mantenha-a confidencial.
Inicie sessão com a sua nova PAT no prazo de 90 dias para organizações apoiadas pelo Microsoft Entra ID; caso contrário, a PAT fica inativa. 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ê recebe uma notificação semelhante ao exemplo a seguir. Esta notificação serve como confirmação de que a sua PAT foi adicionada com êxito à sua organização.

Captura de ecrã a mostrar a notificação criada pela PAT.

A imagem seguinte mostra um exemplo da notificação de sete dias antes de a PAT expirar.

Captura de ecrã a mostrar a notificação de quase expiração da PAT.

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

Notificação inesperada

Se receber uma notificação PAT inesperada, isso pode significar que um administrador ou ferramenta criou uma PAT para si. Seguem-se 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 via 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 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 a PAT se suspeitar que ela existe por engano. Siga os passos para revogar a PAT e alterar a sua palavra-passe.
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.
Consulte as Perguntas frequentes sobre check-ins acidentais da PAT em repositórios públicos do GitHub.

Utilizar uma PAT

O seu PAT serve como a sua identidade digital, tal como uma palavra-passe.

Git

As interações do Git exigem um nome de usuário, que pode ser qualquer coisa, exceto uma cadeia de caracteres vazia. Para usar uma PAT com autenticação básica HTTP, Base64-encode o seu $MyPat como 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 os gerenciadores de credenciais para evitar inserir suas credenciais toda vez e manter seu token mais seguro:

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

Em 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 gerenciadores de credenciais para não precisar inserir suas credenciais sempre. 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 através 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

O path to git repo = /_git/do refere-se à estrutura de caminho de URL usada no Azure DevOps para repositórios Git. O /_git/ segmento indica que você está acessando um repositório Git e deve substituir do pelo nome real do repositório. Por exemplo, se o repositório for nomeado my-repo, o caminho será '/_git/my-repo'.
Repositório de clonagem: se você estiver usando o Git e precisar 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.

Utilize uma PAT no seu código

Pode utilizar uma PAT no seu código para autenticar pedidos de API e automatizar fluxos de trabalho. Para tal, inclua a PAT no cabeçalho de autorização dos seus pedidos HTTP.

Windows
Linux/macOS

Para fornecer a PAT através de um cabeçalho HTTP, primeiro converta-a numa 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 seguinte formato.

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

Gorjeta

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

O exemplo a seguir obtém uma lista de compilações 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 de autenticação básica para OAuth.

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

Modificar uma PAT

Siga os seguintes passos para:

Regenere uma PAT para criar um novo token, que invalida o anterior.
Prolongar um PAT para aumentar o seu período de validade.
Alterar o âmbito de uma PAT para alterar as 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 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 uma PAT

Pode revogar uma PAT a qualquer momento por estes e outros motivos:

Revogue uma PAT se suspeitar que está comprometida.
Revogue uma PAT quando já não for necessária.
Revogar uma PAT para aplicar 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 pretende 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 ao 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 deteção de segredos disponíveis por meio de nossas ofertas de parceiros, como o GitHub Advanced Security for Azure DevOps. Este novo formato PAT segue o formato recomendado em todos os produtos Microsoft. A inclusão de bits mais identificáveis melhora a taxa de deteção de falsos positivos dessas ferramentas de deteção secretas e nos permite mitigar vazamentos detetados mais rapidamente.

Principais alterações:

Maior comprimento do token: Os novos tokens agora têm 84 caracteres, com 52 caracteres sendo dados aleatórios. Esse aumento de comprimento 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 encorajamos 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 aposentar o formato antigo de 52 caracteres e todos os tokens emitidos nesse estilo.

FAQs

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

R: Certifique-se de que tem sessão iniciada na organização onde o PAT tem o âmbito. 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 com escopo da organização quando estiver conectado à organização para a qual eles têm escopo.

P: O que acontece a uma PAT se uma conta de utilizador estiver desativada?

R: Quando um usuário é removido do Azure DevOps, a PAT é invalidada em 1 hora. Se a sua organização estiver ligada ao Microsoft Entra ID, a PAT também invalida no Microsoft Entra ID, uma vez que pertence ao utilizador. Recomendamos que a PAT seja transferida para outro utilizador ou conta de serviço para manter os serviços em execução.

P: Existe uma forma de renovar uma PAT através da API REST?

R: Sim, existe uma forma de renovar, gerir e criar PATs utilizando as nossas APIs de Gestão do Ciclo de Vida da PAT. Para obter mais informações, consulte Gerenciar PATs usando a API REST e as 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 oferecem suporte apenas ao OAuth. Para obter mais informações, consulte Gerenciar PATs usando a API REST.

P: O que acontece se eu verificar acidentalmente a minha PAT num 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 para o proprietário do token e registramos um evento no log de auditoria da sua organização do Azure DevOps. A menos que você tenha desativado 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 de Artefatos do Azure usando a linha de comando dotnet/nuget.exe?

R: Não. Os Artefactos do Azure não suportam a transmissão de um token de acesso pessoal como ApiKey. Ao utilizar um ambiente de desenvolvimento local, recomendamos que instale o Fornecedor de Credenciais dos Artefactos do Azure para se autenticar com os Artefactos do Azure. Para obter mais informações, veja os seguintes exemplos: dotnet, NuGet.exe. Se você quiser publicar seus pacotes usando o Azure Pipelines, use a tarefa NuGet Authenticate para autenticar com seu exemplo de feed.

P: Porque é que o meu PAT deixou de funcionar?

R: A autenticação PAT requer que inicie sessão regularmente no Azure DevOps utilizando 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 a PAT deixar de funcionar, tente primeiro iniciar sessão na sua organização e conclua o pedido de autenticação completo. Se a sua PAT continuar a não funcionar, verifique se 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 Cofre da Chave do Azure no Azure Pipelines.

Partilhar via

Utilizar tokens de acesso pessoal

Pré-requisitos

Criar uma PAT

Notificações

Notificação inesperada

Utilizar uma PAT

Repositórios existentes

Utilize uma PAT no seu código

Modificar uma PAT

Revogar uma PAT

Alterações ao formato

FAQs

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

P: O que acontece a uma PAT se uma conta de utilizador estiver desativada?

P: Existe uma forma de renovar uma PAT através 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 verificar acidentalmente a minha PAT num repositório público no GitHub?

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

P: Porque é que o meu PAT deixou 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

Partilhar via

Utilizar tokens de acesso pessoal

Pré-requisitos

Criar uma PAT

Notificações

Notificação inesperada

Utilizar uma PAT

Repositórios existentes

Utilize uma PAT no seu código

Modificar uma PAT

Revogar uma PAT

Alterações ao formato

Artigos relacionados

FAQs

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

P: O que acontece a uma PAT se uma conta de utilizador estiver desativada?

P: Existe uma forma de renovar uma PAT através 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 verificar acidentalmente a minha PAT num repositório público no GitHub?

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

P: Porque é que o meu PAT deixou 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