Usar tokens de acesso pessoal
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Um PAT (Token de Acesso Pessoal) pode servir como uma senha alternativa para autenticação no Azure DevOps. Este artigo orienta você pelo processo de criação, utilização, modificação e revogação de PATs para Azure DevOps.
Sobre PATs
Um PAT (Token de Acesso Pessoal) serve como suas credenciais de segurança para o Azure DevOps. Este PAT não apenas identifica você, mas também determina sua acessibilidade e escopo de acesso. Portanto, os PATs são tão importantes quanto as senhas e devem ser tratados com o mesmo nível de cautela.
Se você estiver utilizando ferramentas da Microsoft, sua MSA (conta Microsoft) ou ID do Microsoft Entra é um método reconhecido e com suporte. No entanto, se você estiver usando ferramentas de terceiros que não dão suporte a contas da Microsoft ou do Microsoft Entra ou se estiver relutante em compartilhar suas credenciais primárias com essas ferramentas, os PATs são uma alternativa mais segura.
Crie e gerencie PATs das duas maneiras a seguir:
- 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 que você revise nossas diretrizes de autenticação para ajudá-lo a escolher o mecanismo de autenticação apropriado. Os PATs servem como uma alternativa direta para projetos menores que não precisam de uma solução extensa. A menos que um gerenciador de credenciais esteja em uso, os usuários devem inserir 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 permitir que um agente de build e versão se autentique no Azure DevOps, limite o escopo do token a Pools de Agentes (Leitura e gerenciamento). Para ler eventos de log de auditoria e gerenciar e 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 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.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
- Manuseie um PAT com o mesmo cuidado que sua senha e mantenha-o em segredo.
- Para organizações com suporte da ID do Microsoft Entra, é necessário entrar com seu novo PAT dentro de 90 dias; não fazer isso torna o PAT 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.
A imagem a seguir mostra um exemplo da notificação de sete dias antes que o PAT expire.
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 uma implantação de aplicativo Web do Serviço de Aplicativo do Azure é configurada por você ou por um administrador.
- 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
Se você suspeitar que existe um PAT por engano, considere revogar o PAT e alterar sua senha. Como usuário do Microsoft Entra, verifique com o administrador se sua organização foi usada por uma fonte ou local desconhecido. Além disso, consulte 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, representando você quando utilizado, assim como uma senha.
Git
As interações do Git exigem um nome de usuário, que pode ser qualquer coisa, exceto a string vazia.
Para usar um PAT com autenticação básica HTTP, use Base64-encode for $MyPat, que está incluído no bloco de código a seguir.
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
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://dev.azure.com/<PAT>@<company_machineName>:/<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.
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());
}
}
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:
- Gerenciadores de credenciais do Git
- APIs REST
- NuGet em um Mac
- Clientes de relatórios
- Introdução à CLI do Azure DevOps
Modificar um PAT
Você pode regenerar, estender um PAT ou alterar seu escopo. Uma vez regenerado, o PAT anterior torna-se não autorizado.
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 vários motivos.
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, fizemos alterações significativas no 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. Essa alteração no formato PAT segue o novo formato recomendado em todos os produtos da Microsoft. Prevemos que a inclusão de bits mais identificáveis melhorará a taxa de detecção de falsos positivos dessas ferramentas secretas de detecção e nos permitirá mitigar melhor os vazamentos detectados com mais rapidez.
Principais mudanças:
- Aumento do comprimento do token: Os novos tokens são mais longos, agora com 84 caracteres no total. Destes, 52 caracteres são 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
AZDOnas 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.
Como ambos os formatos permanecem válidos no futuro próximo, estamos incentivando ativamente os clientes a fazer a transição para o novo formato de 84 caracteres. À medida que a adoção do novo formato aumenta, consideraremos a desativação do formato antigo de 52 caracteres e de todos os tokens emitidos nesse estilo.
Artigos relacionados
- Sobre segurança, autenticação e autorização
- Permissões e 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
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: Depois que 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 pertence ao usuário. Recomendamos que o usuário alterne seu 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 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 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 imediatamente, 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. Uma vez a cada 30 dias são suficientes para muitos, mas pode ser necessário entrar com mais frequência do que isso, dependendo da configuração do Microsoft Entra. Se o PAT parar de funcionar, primeiro tente entrar na sua organização, garantindo que você passe pelo prompt de autenticação completo. Se o seu PAT ainda não funcionar depois disso, verifique se ele expirou.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de