Usar tokens de acesso pessoal

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Um PAT (token de acesso pessoal) serve como uma senha alternativa para autenticação em Azure DevOps. Os PATs identificam você e determinam sua acessibilidade e escopo de acesso. Trate PATs com o mesmo nível de cuidado que as senhas.

Quando você usa as ferramentas da Microsoft, sua conta da Microsoft ou Microsoft Entra ID é reconhecida e tem suporte. Se você usar ferramentas que não dão suporte a contas Microsoft Entra ou se preferir não compartilhar suas credenciais primárias, considere usar PATs como um método de autenticação alternativo.

Pré-requisitos

Criar um PAT

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

   

3. Selecione + New Token.

   

4. 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.

   

5. Selecione os escopos para esse token, para autorizar as suas tarefas específicas.

   Por exemplo, para criar um token para um agente de build e release autenticar no Azure DevOps, defina o escopo do token como Pools de Agentes (Leitura e gerenciamento). Para ler eventos de logs de auditoria e gerenciar ou excluir fluxos, selecione Ler Log de Auditoria e, em seguida, selecione Criar.

   

   O administrador pode impedir que você crie PATs com escopo completo ou limite-o apenas a PATs de escopo de empacotamento. Entre em contato com o administrador para entrar na lista de permissões se precisar de acesso a mais escopos. Alguns escopos, por exemplo, vso.governance podem não estar disponíveis na interface do usuário (UI) se não forem para uso público generalizado.

6. Quando terminar, copie o token e armazene-o em um local seguro. Para a sua segurança, ele não será exibido novamente.

   

Você pode usar seu PAT em qualquer lugar em que suas credenciais de usuário sejam necessárias para autenticação no Azure DevOps. Lembre-se:

• Trate um PAT com o mesmo cuidado que sua senha e mantenha-o confidencial. Não compartilhe PATs.
• Para organizações apoiadas por Microsoft Entra ID, faça login com seu novo PAT dentro de 90 dias ou ele se tornará inativo. Para obter mais informações, consulte a frequência de entrada do usuário para acesso condicional.

Notificações

Durante o tempo de vida de um PAT, os usuários recebem duas notificações: uma quando o PAT é criado e outra antes de expirar.

Depois de criar um PAT, você poderá 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.

Um email de notificação de expiração é enviado antes que o token expire. Se o administrador removeu sua capacidade de criar PATs na organização, o email indica que não é mais possível regenerar PATs. Entre em contato com o administrador da coleção de projetos para ser incluído em uma lista de autorização para criação contínua de PAT nessa organização.

Notificação inesperada

Se você receber uma notificação PAT inesperada, isso pode indicar que um administrador ou uma ferramenta criou um PAT para você. Estes são alguns exemplos:

• Um token chamado git: https://dev.azure.com/{yourorganization} on YourMachine é criado quando você se conecta a um repositório git Azure DevOps por meio de git.exe.
• Um token chamado Service Hooks: Azure App Service: Deploy web app é criado quando você ou um administrador configura uma implantação de aplicativo Web Azure App Service.
• 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 Microsoft Teams Integration é criado quando uma Extensão de Mensagens de Integração Microsoft Teams é configurada.

Se você acha que a situação é séria:

• Revogue o PAT (e altere sua senha) se você suspeitar que ele existe em erro.
• Verifique com o administrador se você é um Microsoft Entra usuário para ver se uma origem ou local desconhecido acessou sua organização.
• Examine as perguntas frequentes sobre accidental PAT check-ins para repositórios públicos de GitHub.

Usar um PAT

Seu PAT serve como a sua identidade digital, parecido a uma senha. Você pode usar PATs como uma maneira rápida de fazer solicitações pontuais ou protótipo de um aplicativo localmente. Use um PAT em seu código para autenticar solicitações de API REST e automatizar fluxos de trabalho, incluindo o PAT no cabeçalho de autorização de sua solicitação.

Depois que o código do aplicativo estiver funcionando, alterne para Microsoft Entra OAuth para adquirir tokens para os usuários do aplicativo ou uma entidade de serviço ou identidade gerenciada para adquirir tokens como um aplicativo. Não continue executando aplicativos ou scripts com PATs a longo prazo. Você pode usar Microsoft Entra tokens em qualquer lugar em que um PAT seja usado.

Considere adquirir um token Microsoft Entra por meio do Azure CLI para solicitações não planejadas.

Authorization: Basic BASE64_USERNAME_PAT_STRING

curl -u :{PAT} https://dev.azure.com/{organization}/_apis/build-release/builds

Modificar um PAT

Execute as etapas abaixo para:

• Regenerar um PAT para criar um novo token, o que invalida o anterior.
• Ampliar um PAT para aumentar seu período de validade.
• Modificar o escopo de um PAT para alterar suas permissões.

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

2. Selecione o token que você deseja modificar e selecione Editar.

   

3. Edite o nome, a data de expiração ou o escopo de acesso associados ao token e selecione Salvar.

   

Revogar um PAT

Você pode revogar um PAT a qualquer momento pelos motivos abaixo, e outros:

• Violação de segurança: revogue um PAT imediatamente se você suspeitar que ele foi comprometido, vazado ou exposto em logs ou repositórios públicos.
• Não é mais necessário: revogar um PAT quando o projeto, o serviço ou a integração para o qual ele foi criado for concluído.
• Conformidade com política: revogar um PAT para impor políticas de segurança, requisitos de conformidade ou cronogramas de rotação de tokens organizacionais.
• Alterações de usuário: revogar um PAT quando um membro da equipe sair da organização ou alterar as funções e não precisar mais de acesso.
• Redução de escopo: revogar e recriar um PAT com permissões reduzidas quando precisar limitar seus recursos de acesso.
• Manutenção regular: revogar um PAT como parte da higiene de segurança de rotina e do gerenciamento do ciclo de vida do token.

Para revogar um PAT, siga estas etapas:

1. Em sua home page, abra as configurações do usuário e selecione tokens de acesso pessoal.

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.

   

3. Na caixa de diálogo Confirmação , selecione Revogar.

   

APIs de Gerenciamento de Ciclo de Vida do PAT

As APIs de Gerenciamento de Ciclo de Vida do PAT podem ser úteis quando a manutenção de grandes volumes de tokens por meio da interface do usuário é insustentável. Gerenciar a rotação de PATs programaticamente também abre a oportunidade de rotacionar PATs regularmente e encurtar seus tempos de vida padrão. Você pode configurar o aplicativo de exemplo Python com seu locatário Microsoft Entra e sua organização do Azure DevOps.

Algumas coisas a serem observadas sobre estas APIs:

• Microsoft Entra tokens de acesso são necessários para acessar essa API. Use uma forma mais forte de autenticação ao criar novos tokens.
• Somente usuários ou aplicativos que usam um fluxo "em nome do usuário" podem gerar PATs. Aplicativos que usam fluxos "em nome do aplicativo" ou fluxos de autenticação que não emitem tokens de acesso Microsoft Entra não são válidos para uso com esta API. Dessa forma, entidades de serviço ou identidades gerenciadas não podem criar ou gerenciar PATs.
• Anteriormente, os escopos compatíveis com as APIs de Gerenciamento de Ciclo de Vida do PAT eram limitados ao user_impersonation, mas agora o vso.pats está disponível e é o escopo recomendado para ser usado com essas APIs. Reduza o escopo de todos os aplicativos que anteriormente dependiam de user_impersonation para chamar essas APIs.

Formato PAT

As strings PAT usam um formato específico projetado para melhorar a detecção de segredos nas ferramentas de detecção de PATs vazados e ofertas de parceiros. O formato inclui bits identificáveis que melhoram a taxa de detecção de falsos positivos e permitem uma mitigação mais rápida de vazamentos detectados.

• Os tokens têm 84 caracteres, com 52 caracteres sendo dados aleatórios, o que melhora a entropia geral. Os tokens são resistentes a ataques de força bruta.
• Os tokens emitidos por Azure DevOps incluem uma assinatura AZDO fixa nas posições 76-80.

Se você integrar com PATs e tiver a validação de PAT interna, verifique se o código de validação acomoda o comprimento do token de 84 caracteres.

Práticas recomendadas para usar PATs

Alternativas a serem consideradas

• Adquira um token Microsoft Entra por meio do Azure CLI para solicitações imprevistas em vez de criar um PAT (Token de Acesso Pessoal) de vida mais longa.
• Use gerentes de credenciais como Git Credential Manager ou Azure Artifacts Credential Manager para simplificar o gerenciamento de credenciais, com a autenticação definida como tokens oauth ou Microsoft Entra.

Criar PATs

• Não coloque dados pessoais no nome do PAT. Não renomeie o nome PAT para incluir parte ou todo o token PAT real.
• Evite criar PATs globais, a menos que seja necessário em todas as organizações.
• Use um token diferente por fluxo ou caso de uso.
• Selecione apenas os escopos mínimos necessários para cada PAT. Conceda o privilégio mínimo necessário para sua tarefa específica. Crie PATs separadas com escopos limitados para fluxos de trabalho diferentes em vez de usar um único token de escopo amplo. Se o PAT precisar de permissões de apenas leitura, não forneça permissões de gravação até que seja necessário.
• Mantenha o tempo de vida do PAT curto.

Gerenciar PATs

• Não compartilhe seus PATs!
• Store seus PATs em uma solução de gerenciamento de chave segura, como Azure Key Vault.
• Gire ou regenere regularmente os seus PATs pela interface do usuário ou por meio das APIs de gerenciamento do ciclo de vida dos PATs.
• Revogar os PATs quando eles não forem mais necessários.

Para administradores

• Os administradores de locatários podem definir políticas para restringir a criação global do PAT, a criação de PAT com escopo completo e a duração do PAT de longa duração.
• Os administradores de locatários podem revogar PATs para seus usuários da organização se o PAT estiver comprometido.
• Os administradores da organização podem restringir a criação de PAT em uma organização. Se os PATs ainda forem necessários, limite sua criação apenas para PATs que estão na lista de permissões.

Perguntas Frequentes

Q. Por que não posso editar ou regenerar um PAT definido para uma única organização?

A. Entre na organização onde seu PAT está definido. Você pode visualizar seus PATs quando estiver logado em qualquer organização do mesmo Microsoft Entra ID alterando o filtro de escopo de acesso. Você só pode editar tokens no escopo da organização quando estiver conectado à organização específica.

Q. O que acontece com um PAT se uma conta de usuário estiver desabilitada?

A. Quando um usuário é removido do Azure DevOps, o PAT é invalidado dentro de uma hora. Se sua organização estiver conectada a Microsoft Entra ID, o PAT também será invalidado em Microsoft Entra ID porque pertence ao usuário. Gire o PAT para outro usuário ou conta de serviço para manter os serviços em execução.

Q. Posso usar PATs com todas as APIs REST Azure DevOps?

A. Não. Você pode usar PATs com a maioria das APIs REST Azure DevOps, mas organizações e perfis e as APIs de Ciclo de Vida de Gerenciamento de PAT dão suporte apenas a tokens Microsoft Entra.

Q. O que acontece se eu acidentalmente verificar meu PAT em um repositório público em GitHub?

A. Azure DevOps verifica se há PATs vazadas em repositórios de GitHub públicos. Quando detectado, Azure DevOps notifica o proprietário do token e registra o evento em seu log audit. A menos que sejam desabilitados, os PATs vazados serão revogados automaticamente. Para obter mais informações, consulte Revogar automaticamente PATs vazados.

Q. Posso usar um token de acesso pessoal como uma chave de API para publicar pacotes NuGet em um feed de Azure Artifacts usando a linha de comando dotnet/nuget.exe?

A. Não. Azure Artifacts não dá suporte à passagem de um PAT como uma chave de API. Ao usar um ambiente de desenvolvimento local, instale o Azure Artifacts Provedor de Credenciais para autenticar com Azure Artifacts. Para obter mais informações, consulte os seguintes exemplos: dotnet e NuGet.exe. Se você quiser publicar seus pacotes usando Azure Pipelines, use a tarefa NuGet Authenticate para autenticar-se no feed. Para obter mais informações, consulte o exemplo em Publicar pacotes NuGet com o Azure Pipelines (YAML/Classic).

Q. Por que meu PAT parou de funcionar?

A. A autenticação pat exige que você entre regularmente no Azure DevOps usando 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 o PAT parar de funcionar, primeiro tente entrar em sua organização e concluir o prompt de autenticação completo. Se o seu PAT continuar não funcionando, comprove se ele expirou.

Para Azure DevOps Server, habilitar a autenticação básica IIS invalida o uso de PAT. Mantenha a Autenticação Básica do IIS desativada.

Q. Como faço para criar tokens de acesso que não estão vinculados a um usuário específico?

A. Os PATs são sempre associados à identidade do usuário que os criou. Para usar tokens não vinculados a um usuário específico, use tokens Microsoft Entra emitidos por um principal de serviço de aplicativo ou identidade gerenciada. Para os pipelines, use conexões de serviço para autenticar sem usar credenciais específicas de usuários. Saiba mais sobre a redução do uso de PAT no Azure DevOps.

Q. Como posso regenerar/girar PATs por meio da API? Vi essa opção na interface do usuário, mas não vejo um método semelhante na API.

A. A funcionalidade Regenerar disponível na interface do usuário realmente realiza algumas ações, que você pode replicar por meio de uma API.

Para girar seu PAT, siga estas etapas:

1. Veja os metadados PAT com uma chamada GET.
2. Crie um novo PAT com a ID de PAT antiga usando uma chamada POST .
3. Revogue o PAT antigo usando uma chamada DELETE .

Q. Por quanto tempo um PAT expirado, revogado ou inativo permanece visível na lista de tokens Azure DevOps?

A. Você não pode mais usar ou regenerar PATs expiradas ou revogadas. Esses tokens inativos permanecem visíveis por vários meses após a expiração ou revogação antes de serem removidos automaticamente da exibição.

Q. Por que vejo uma mensagem "Preciso de aprovação do administrador" ao tentar usar um aplicativo Microsoft Entra para chamar as APIs de Gerenciamento de Ciclo de Vida do PAT?

A. As políticas de segurança do locatário exigem consentimento do administrador para que os aplicativos possam acessar os recursos da organização. Entre em contato com o administrador do locatário.

Usar a IA para gerenciar tokens de acesso pessoal

Se você tiver o Azure DevOps MCP Server configurado, poderá usar assistentes de IA para gerenciar e revisar seus personal access tokens usando comandos em linguagem natural. O SERVIDOR MCP fornece ao assistente de IA acesso seguro aos seus dados de Azure DevOps, permitindo que você liste tokens, verifique as datas de expiração e examine os escopos de token sem navegar pela interface da Web.

Prompts de exemplo para gerenciar tokens de acesso pessoal

Conteúdo relacionado

• Revogar PATs de usuário (para administradores)
• Autenticar usando tokens do Microsoft Entra