Usar tokens de acesso pessoal
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Um Personal Access Token (PAT) 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 o 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. Por isso, os PATs são tão importantes quanto as senhas e devem ser manuseados com o mesmo nível de cautela.
Se você estiver utilizando ferramentas da Microsoft, sua conta da Microsoft (MSA) ou ID do Microsoft Entra é um método reconhecido e com suporte. No entanto, se você estiver usando ferramentas de terceiros que não oferecem suporte a contas da Microsoft ou do Microsoft Entra, ou se estiver relutante em compartilhar suas credenciais principais com essas ferramentas, os PATs são uma alternativa mais segura.
Crie e gerencie PATs das duas maneiras a seguir:
- Interface do usuário (UI): 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 sejam da Microsoft, você pode usar gerenciadores de credenciais do 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 simples 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 onde deseja usar o token e defina seu token para expirar automaticamente após um número definido de dias.
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 compilação e liberação se autentique no Azure DevOps, limite o escopo do token a Pools de Agentes (Leia e gerencie). Para ler eventos de log de auditoria e gerenciar e excluir fluxos, selecione Ler Log de Auditoria e selecione Criar.
Observação
Você pode estar impedido de criar PATs com escopo completo. Nesse caso, o Administrador de DevOps do Azure na ID do Microsoft Entra habilitou uma política que limita você a um conjunto específico de escopos definidos e 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 Componente,
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 onde 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 do Microsoft Entra ID, é necessário entrar com seu novo PAT dentro de 90 dias; se isso não for feito, o PAT ficará 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ê recebe 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 seu PAT expire.
Para obter mais informações, consulte Configurar um servidor SMTP e personalizar o email para alertas e solicitações de comentários.
Notificação inesperada
Se você receber uma notificação PAT inesperada, isso pode significar que um administrador ou ferramenta criou um PAT para você. Aqui estão alguns exemplos.
- Um token chamado "git:
https://MyOrganization.visualstudio.com/on MyMachine" é 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 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 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 um PAT existe 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 de PAT em repositórios públicos do GitHub.
Usar 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 cadeia de caracteres vazia.
Para usar um PAT com autenticação básica HTTP, use Base64-encode para $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á tiver adicionado a origem usando o nome de usuário, execute o seguinte comando primeiro.
git remote remove origin
Caso contrário, execute o seguinte comando.
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
Use 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 o Base64 uso de C#.
Authorization: Basic BASE64_USERNAME_PAT_STRING
A cadeia de caracteres resultante pode então 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());
}
}
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 seu código está funcionando, é um bom momento para mudar da autenticação básica para 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 com relatórios
- Introdução à CLI de DevOps do Azure
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 home page, abra as configurações do usuário e selecione Perfil.
Em Segurança, selecione Tokens de acesso pessoais. Selecione o token que deseja modificar e 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 home page, abra as configurações do usuário e selecione Perfil.
Em Segurança, selecione Tokens de acesso pessoais. 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.
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 consigo editar ou regenerar um PAT com escopo definido para uma única organização?
R: Verifique se você está conectado à organização onde seu PAT tem 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 com escopo da organização quando estiver conectado à organização para a qual eles têm 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 dentro de 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 gire seu PAT para outra conta de usuário ou serviço para manter os serviços em execução.
P: Existe uma maneira de renovar um PAT via 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 oferecem suporte apenas a 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 com check-in em 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 sua organização de DevOps do Azure. A menos que você desabilite a política Revogar automaticamente tokens de acesso pessoal vazados, revogamos imediatamente o PAT vazado. Encorajamos 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 de Artefatos do Azure 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 NuGet Authenticate para autenticar com seu 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 é suficiente para muitos, mas talvez seja 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 PAT continuar a não funcionar depois disso, verifique se o PAT 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