Usar tokens de acesso pessoal

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

Um PAT (token de acesso pessoal) serve como uma senha alternativa para autenticação no 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 a ID do Microsoft Entra são reconhecidas e têm suporte. Se você usar ferramentas que não dão suporte a contas do Microsoft Entra ou se preferir não compartilhar suas credenciais primárias, considere usar PATs como um método de autenticação alternativo. Recomendamos que você use tokens do Microsoft Entra em vez de PATs sempre que possível.

Pré-requisitos

Criar um PAT

1. Entre em sua organização (https://dev.azure.com/{Your_Organization}).

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 versão para autenticação no Azure DevOps, defina o escopo do token como Pools de Agentes (Ler e gerenciar). 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.governancepodem não estar disponíveis na interface do usuário (interface do usuário) 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. Lembrar:

• Trate um PAT com o mesmo cuidado que sua senha e mantenha-o confidencial. Não compartilhe PATS.
• Para organizações que têm o apoio da ID do Microsoft Entra, você deve entrar com seu novo PAT dentro de 90 dias ou ele fica 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 outro sete dias 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 três dias antes da expiração. 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 permissões para permissões de criação de PAT contínuas 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 nomeado 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 nomeado Service Hooks: Azure App Service: Deploy web app é criado quando você ou um administrador configura uma implantação de aplicativo Web do Serviço de Aplicativo do Azure.
• Um token nomeado WebAppLoadTestCDIntToken é criado quando o teste de carga da Web é configurado como parte de um pipeline por você ou por um administrador.
• Um token nomeado Microsoft Teams Integration é criado quando uma Extensão de Mensagens de Integração do 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 usuário do Microsoft Entra para ver se uma origem ou um local desconhecido acessou sua organização.
• Verifique as perguntas frequentes sobre Check-ins acidentais do PAT em repositórios públicos do 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 o 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 recomendamos que você continue executando aplicativos ou scripts com PATs a longo prazo. Você pode usar tokens do Microsoft Entra em qualquer lugar em que um PAT seja usado.

Considere a aquisição de um token do Microsoft Entra por meio da CLI do Azure para solicitações ad hoc.

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 ou descontinuado.
• 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 Python de exemplo com seu locatário do Microsoft Entra e a organização do Azure DevOps.

Algumas coisas a serem observadas sobre estas APIs:

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

Alterações no formato

A partir de julho de 2024, atualizamos o formato de cadeias de caracteres de PAT para melhorar a detecção de segredos em nossas ferramentas de detecção de PAT vazadas e ofertas de parceiros. Esse novo formato PAT inclui bits mais identificáveis para melhorar a taxa de detecção de falsos positivos nessas ferramentas de detecção e reduzir os vazamentos detectados mais rapidamente.

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

Se você estiver usando um PAT emitido antes dos dados, regenere o PAT. Se você se integrar a PATs e tiver a validação de PATs incorporada, atualize seu código de validação para acomodar os comprimentos de token novos e existentes.

Práticas recomendadas para usar PATs

Alternativas a serem consideradas

• Adquira um token do Microsoft Entra por meio da CLI do Azure para solicitações ad hoc em vez de criar um PAT de vida mais longa.
• Use gerenciadores de credenciais como o Git Credential Manager ou o Azure Artifacts Credential Manager para simplificar o gerenciamento de credenciais, com autenticação definida como oauth ou como tokens do 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 usuário.
• 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. (Semanalmente é ideal, e ainda mais curto é melhor.)

Gerenciar PATs

• Não compartilhe seus PATs!
• Armazene seus PATs em uma solução de gerenciamento de chaves segura, como o Azure Key Vault.
• Gire ou regenere regularmente seus PATs por meio da interface do usuário ou usando APIs de Gerenciamento do Ciclo de Vida do PAT.
• Revogue pats quando elas não forem mais necessárias.
• Gire seus PATs para usar o novo formato PAT para melhor detecção e revogação de segredos vazados por nossas ferramentas de primeira parte.

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 com escopo para uma única organização?

A. Entre na organização em que seu PAT está no escopo. Você pode exibir seus PATs quando estiver conectado a qualquer organização na mesma ID do Microsoft Entra alterando o filtro de escopo do Access . 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 em uma hora. Se sua organização estiver conectada à ID do Microsoft Entra, o PAT também será invalidado na ID do Microsoft Entra porque pertence ao usuário. Recomendamos que você 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 do Azure DevOps?

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

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

A. O Azure DevOps verifica pats que são 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 organização no Azure DevOps. Incentivamos os usuários afetados a mitigarem o problema revogando o token vazado e substituindo-o por um novo token.

A menos que você tenha desabilitado a política Revogar automaticamente tokens de acesso pessoal vazados, o PAT vazado é imediatamente revogado por nós. 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 do Azure Artifacts usando a linha de comando dotnet/nuget.exe?

A. Não. O Azure Artifacts não dá suporte à passagem de um PAT como uma chave de API. Ao usar um ambiente de desenvolvimento local, recomendamos que você instale 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 Autenticação do NuGet para autenticar com o feed. Para obter mais informações, consulte o exemplo em Publicar pacotes NuGet com o Azure Pipelines (YAML/Clássico).

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. Para muitos usuários, entrar uma vez a cada 30 dias é suficiente, mas pode ser que você tenha que 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 conclua o prompt de autenticação completo. Se o seu PAT continuar não funcionando, comprove se ele expirou.

Habilite a Autenticação Básica do IIS invalida usando PATs para Azure DevOps Server. Recomendamos que você sempre mantenha a Autenticação Básica do IIS desativada.

git -c http.extraheader='Authorization: Basic [base 64 encoding of "user:password"]' ls-remote http://tfsserver:8080/tfs/DefaultCollection/_git/projectName

Q. Como faço para criar tokens de acesso que não estão vinculados a uma pessoa?

A. Todos os PATs são associados à identidade do usuário que a criou. Os aplicativos não podem criar PATs.

No Azure DevOps, você pode gerar tokens de acesso que não estão vinculados a um usuário específico. Use tokens do Microsoft Entra emitidos por uma entidade de serviço de aplicativo ou identidade gerenciada . Para pipelines, use conexões de serviço para autenticar e autorizar tarefas automatizadas com segurança sem depender de credenciais específicas do usuário.

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. Consulte 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 os PATs expirados, revogados ou inativos permanecem visíveis na lista de tokens do 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 do 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 antes que os aplicativos possam acessar os recursos da organização na organização. Entre em contato com o administrador do locatário.

Q. Posso usar uma entidade de serviço para criar ou gerenciar PATs?

A. Não. Os PATs pertencem a uma identidade de usuário. Entidades de serviço ou identidades gerenciadas do Microsoft Entra podem gerar tokens do Microsoft Entra de curta duração que você pode usar na maioria dos lugares em que um PAT é aceito. Saiba mais sobre nossos esforços para reduzir o uso de PAT no Azure DevOps e explorar a substituição de PATs por tokens do Microsoft Entra.

Conteúdo relacionado

• Usar políticas para gerenciar tokens de acesso pessoal para usuários
• Revogar PATs de usuário (para administradores)
• Autenticação com tokens do Microsoft Entra