Compartilhar via

Usar tokens de acesso pessoal

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Os Tokens de acesso Pessoal (PATs) servem 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 ferramentas da Microsoft, sua conta da Microsoft (MSA) ou do Microsoft Entra ID é reconhecida e suportada. 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. No entanto, é recomendável usar tokens do Microsoft Entra em vez de PATs sempre que possível.

Importante

Recomendamos os tokens mais seguros do Microsoft Entra em vez de tokens de acesso pessoal de maior risco. Saiba mais sobre nossos esforços para reduzir o uso do PAT. Examine nossas diretrizes de autenticação para escolher o mecanismo de autenticação correto para suas necessidades.

Pré-requisitos

Categoria Requisitos
Permissões Permissão para acessar e modificar as configurações do usuário em que os PATs são gerenciados.
- Vá para seu perfil e selecione Configurações de usuário>Tokens de Acesso Pessoal. Se você pode ver e gerenciar seus PATs aqui, então tem as permissões necessárias.
- Vá para 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 de usuário.
- Se sua organização tiver políticas em vigor, talvez um administrador precise conceder permissões específicas ou adicioná-lo a uma lista de permissões para criar e gerenciar PATs.
- Os PATs estão vinculados à conta de usuário que criou o token. Dependendo das tarefas executadas pelo PAT, você pode precisar de mais permissões por conta própria.
Níveis de Acesso No mínimo, acesso Básico.
Tarefas Use PATs somente quando necessário e sempre faça a rotação deles regularmente. Consulte nossa seção sobre práticas recomendadas ao usar PATs.

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.

    Captura de tela mostrando a seleção, Tokens de acesso pessoal.

  3. Selecione + New Token.

    Captura de tela mostrando a seleção, Novo 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.

    Captura de tela mostrando a entrada de informações básicas do token.

  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.

    Captura de tela mostrando escopos selecionados para um PAT.

    Observação

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

    Captura de tela mostrando como copiar o token para a área de transferência.

Utilize seu PAT em qualquer lugar em que as suas credenciais de usuário sejam necessárias para autenticação no Azure DevOps.

Importante

  • Trate um PAT com a mesma precaução que a sua senha e mantenha-o confidencial. NÃO COMPARTILHAR PATS.
  • Para organizações apoiadas pelo Microsoft Entra ID, você deve fazer login com seu novo PAT dentro de 90 dias ou ele ficará inativo. Para obter mais informações, consulte 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.

Captura de tela mostrando a notificação de criação de PAT.

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, permitindo a criação contínua de PATs nessa organização.

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

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:

  • Quando você se conecta a um repositório Git do Azure DevOps por meio de git.exe, um token chamado "git: https://dev.azure.com/{Your_Organization} on YourMachine" é criado.
  • 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 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

Usar um PAT

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

Importante

Depois que o código do aplicativo estiver funcionando, alterne para o Microsoft Entra OAuth para adquirir tokens em nome dos usuários do aplicativo ou uma entidade de serviço ou identidade gerenciada para adquirir tokens como um aplicativo. Não é recomendável continuar executando aplicativos ou scripts com PATs a longo prazo. Os tokens do Microsoft Entra podem ser usados 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.

Para fornecer o PAT por meio de um cabeçalho HTTP, primeiro você deve convertê-lo em uma Base64 cadeia de caracteres. Em seguida, ele pode ser fornecido como um cabeçalho HTTP no formato a seguir.


Authorization: Basic BASE64_USERNAME_PAT_STRING

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 deseja modificar e, em seguida, Editar.

    Captura de tela mostrando o botão Editar destacado para modificar o PAT.

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

    Captura de tela mostrando o PAT modificado.

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 está 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 de política: Revogar um token de acesso pessoal (PAT) para impor políticas de segurança, atender requisitos de conformidade ou seguir cronogramas de rotação de token organizacional.
  • 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.

Execute as seguintes etapas para revogar um PAT:

  1. Na sua página inicial, 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.

    Captura de tela mostrando a seleção para revogar um único token ou todos os tokens.

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

    Captura de tela mostrando a tela de confirmação de revogação do PAT.

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. Nosso aplicativo Python de exemplo pode ser configurado 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, pois geralmente uma forma mais forte de autenticação é recomendada ao criar novos tokens.
  • Somente usuários ou aplicativos que usam um fluxo "em nome do usuário" podem gerar PATs. Os aplicativos que usam fluxos "em nome de aplicativo" ou fluxos de autenticação que não emitem tokens de acesso do 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, as APIs de Gerenciamento de Ciclo de Vida do PAT só suportavam o user_impersonation escopo, mas agora o vso.pats está disponível e é o escopo recomendado para utilizar 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, tornando os tokens 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.

Aviso

Ambos os formatos permanecem válidos para o futuro previsível. À medida que a adoção do novo formato aumenta, podemos desativar PATs de 52 caracteres mais antigos.

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.

Criação de 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 e 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 a durabilidade do PAT curta (uma duração semanal é ideal, ainda mais curta é melhor).

Gerenciamento de PATs

  • Não compartilhe seus PATs!
  • Armazene seus PATs em uma solução de gerenciamento de chave segura, como o Azure KeyVault.
  • Gire ou regenere regularmente seus PATs por meio da interface do usuário ou das APIs de Gerenciamento do Ciclo de Vida do PAT.
  • Revogar PATs quando não forem mais necessários.
  • Alterne seus PATs para usar o novo formato PAT para melhor detecção e revogação de segredos vazados por nossas ferramentas originais.

Para administradores

Perguntas Frequentes

P: Por que não consigo editar ou regenerar um PAT restrito a uma única organização?

R: Faça login na organização cujo escopo abrange seu PAT. Você pode exibir seus PATs quando estiver logado em qualquer organização na mesma ID do Microsoft Entra alterando o filtro de escopo de acesso, mas só poderá editar tokens com escopo da organização quando estiver logado na organização específica.

P: O que acontece com um PAT se uma conta de usuário for desativada?

R: Quando um usuário é removido do Azure DevOps, o PAT é invalidado no lapso de 1 hora. Se a sua organização estiver conectada ao Microsoft Entra ID, o PAT também será invalidado no Microsoft Entra ID, pois ele pertence ao usuário. Recomendamos rotacionar o PAT para outro usuário ou conta de serviço, para manter os serviços em execução.

P: posso usar PATs com todas as APIs REST do Azure DevOps?

R: 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 só dão suporte a tokens do Microsoft Entra.

P: O que acontece se eu fizer check-in do meu PAT acidentalmente em um repositório público no GitHub?

R: O Azure DevOps rastreia 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 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.

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 dá suporte à passagem de um PAT como uma Chave de API. 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 quiser publicar seus pacotes usando o Azure Pipelines, use a tarefa de Autenticação NuGet para autenticar com seu feed. Confira o exemplo.

P: Por que meu PAT parou de funcionar?

R: A autenticação PAT exige que você entre regularmente no Azure DevOps utilizando 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 seu PAT parar de funcionar, primeiro tente entrar na sua organização e preencher 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ê mantenha Autenticação Básica do IIS sempre desativada .

Aviso

Se você usar o Git com a Autenticação Básica do IIS, o Git será interrompido porque ele requer PATs para autenticação do usuário. Você pode adicionar um cabeçalho extra às solicitações do Git para usá-lo com a Autenticação Básica do IIS, mas não recomendamos essa ação. O cabeçalho extra deve ser usado para todas as instalações do Azure DevOps Server, pois o Windows Auth também impede o uso de PATs. O cabeçalho extra também deve incluir uma codificação base 64 de user:PAT.

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

P: Como criar tokens de acesso que não estão vinculados a uma pessoa?

R: Todos os PATs estã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 usando 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.

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

R: A funcionalidade 'Regenerar' disponível na interface do usuário realmente realiza algumas ações, que podem ser replicadas por meio da API.

Para girar seu PAT, execute as seguintes etapas:

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

P: Por quanto tempo os PATs expirados, revogados ou inativos permanecem visíveis na lista de tokens do Azure DevOps?

R: PaTs expirados ou revogados não podem mais ser usados ou regenerados. 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.

P: Vejo um pop-up "Precisa de aprovação do administrador" quando tento usar um aplicativo do Microsoft Entra para chamar as APIs de Gerenciamento do Ciclo de Vida do PAT.

R: 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.

P: Posso usar uma entidade de serviço para criar ou gerenciar PATs?

R: Não, 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.