Usar tokens de acesso pessoal

Serviços Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Um PAT (token de acesso pessoal) é uma senha alternativa para autenticação Azure DevOps. Um PAT identifica você e determina os recursos e as operações disponíveis para você. Trate um PAT com o mesmo cuidado que uma senha.

Cuidado

Evite PATs quando um método de autenticação mais seguro estiver disponível. Para aplicativos e automação, use tokens do Microsoft Entra, identidades gerenciadas ou entidades de serviço sempre que possível.

Se uma ferramenta não oferecer suporte à autenticação do Microsoft Entra, use um PAT no escopo da organização com os escopos mínimos e o menor tempo de vida prático possível.

Importante

Azure DevOps está desativando PATs globais. Todas as PATs globais existentes param de funcionar em 1º de dezembro de 2026. Migre-os agora para PATs com escopo da organização ou para a autenticação Microsoft Entra. Para obter mais informações, consulte Descontinuação dos Tokens de Acesso Pessoal Globais no Azure DevOps.

Pré-requisitos

• Acesso a uma organização Azure DevOps ou coleção de Azure DevOps Server.
• As permissões necessárias para os recursos e operações que o PAT acessa. Um PAT não pode conceder mais permissões do que aquelas que seu proprietário tem.

• Permissão para criar PATs nas políticas da sua organização. Um administrador pode restringir a criação, os escopos e os tempos de vida do PAT. Para obter mais informações, consulte Gerenciar PATs com políticas.

Criar um PAT

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

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

   

3. Selecione + New Token.

   

4. Insira um nome, selecione uma organização e defina uma data de validade.

   

5. Selecione apenas os escopos necessários para as tarefas pretendidas.

   Por exemplo, para registrar um agente auto-hospedado, selecione Pools de Agentes (Ler & gerenciar). Seu administrador pode restringir PATs com escopo completo ou exigir uma entrada em uma lista de permissões para escopos específicos.

   

6. Selecione Criar, copie o token e armazene-o em um local seguro. O valor do token não aparece novamente.

   

Para organizações com suporte do Microsoft Entra ID, faça login usando um novo PAT dentro de 90 dias, ou ele se tornará inativo. Para obter mais informações, consulte Frequência de entrada do usuário para acesso condicional.

Notificações

Azure DevOps envia uma notificação quando você cria um PAT e outra notificação antes de expirar.

Se uma política de organização não permitir mais regenerar um PAT, o email de expiração identificará a restrição. Entre em contato com o administrador da coleção de projetos se precisar de uma entrada de lista de permissões.

Notificação inesperada

Uma notificação inesperada pode significar que um administrador ou ferramenta criou um PAT para você. Nomes de token comuns incluem:

• git: https://dev.azure.com/{organization} on {machine}, criado quando o Git se conecta a um repositório Azure Repos.
• Service Hooks: Serviço de Aplicativo do Azure: Deploy web app, criado quando uma implantação de Serviço de Aplicativo do Azure é configurada.
• Microsoft Teams Integration, criado quando uma integração de Microsoft Teams é configurada.

Se você não reconhecer um PAT, revogue-o e altere sua senha. No caso de uma conta Microsoft Entra, peça ao seu administrador para analisar atividades de entrada suspeitas.

Usar um PAT

Use um PAT para solicitações pontuais, protótipos locais ou ferramentas que não dão suporte à autenticação Microsoft Entra. Não use PATs como credenciais de longo prazo para aplicativos ou serviços de produção.

Azure DevOps aceita um PAT por meio de um cabeçalho de autenticação HTTP Basic. O nome de usuário pode estar vazio. Codificar a :{PAT}cadeia de caracteres em Base64 e usar o valor resultante neste cabeçalho:

Authorization: Basic BASE64_ENCODED_PAT

Os exemplos a seguir pressupõem que a variável de ambiente AZURE_DEVOPS_PAT seja preenchida a partir de uma fonte segura de segredos.

Windows

$patBytes = [Text.Encoding]::ASCII.GetBytes(":$env:AZURE_DEVOPS_PAT")
$headers = @{ Authorization = "Basic $([Convert]::ToBase64String($patBytes))" }

Invoke-RestMethod `
  -Uri "https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=7.1" `
  -Headers $headers

Linux/macOS

curl --user ":${AZURE_DEVOPS_PAT}" \
  "https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=7.1"

Depois que um protótipo funcionar, migre-o para Microsoft Entra OAuth para acesso delegado ao usuário ou uma entidade de serviço ou identidade gerenciada para acesso ao aplicativo.

Modificar um PAT

Você pode alterar o nome, a expiração ou os escopos de um PAT. A regeneração de um PAT cria um novo valor de token e invalida o valor anterior. Você não pode modificar ou regenerar um PAT expirado ou revogado; em vez disso, crie um novo.

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

2. Selecione o PAT e, em seguida, selecione Editar.

   

3. Altere o nome do token, a expiração ou os escopos e selecione Salvar.

   

Revogar um PAT

Revogue um PAT quando ele estiver comprometido, não for mais necessário ou tiver mais acesso do que o necessário.

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

2. Selecione o PAT e, em seguida, selecione Revogar.

   

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

   

Substituir um PAT expirando ou revogado

Depois que um PAT expira ou é revogado, Azure DevOps rejeita as tentativas de autenticação subsequentes que o usam. Um pipeline, script, cliente de pacote ou operação do Git normalmente falha na próxima vez que tentar se autenticar. Azure DevOps não garante que a revogação encerre todas as conexões já estabelecidas.

Rotacione um PAT antes que ele expire

Para substituir um PAT sem uma interrupção de serviço evitável:

1. Crie um PAT com escopo no nível da organização, com apenas os escopos necessários e curta duração.

2. Armazene o novo valor em seu repositório secreto. Não incorpore PATs em URLs remotas do Git, .git/config, código-fonte, arquivos YAML de pipeline ou logs.

3. Teste o novo PAT com uma operação de não produção ou uma integração antes de atualizar todas as dependências.

4. Atualize cada serviço ou ferramenta que armazena o PAT antigo:

   Integration	Onde atualizar a credencial
   Git	Git Credential Manager ou outro gerenciador de credenciais segura
   Azure Pipelines	Uma variável secreta, um grupo de variáveis ou uma conexão de serviço
   Azure Artifacts	O provedor de credenciais Azure Artifacts ou a configuração segura do gerenciador de pacotes
   Scripts e clientes REST	Um repositório secreto ou variável de ambiente protegido
   Ferramentas de terceiros	Repositório de credenciais seguras da ferramenta

5. Teste cada integração atualizada. Execute o pipeline afetado, a operação do Git, a operação do pacote, o script ou a solicitação de API e verifique se há falhas de autenticação.

6. Revogue o PAT antigo.

Mantenha um inventário de cada PAT, incluindo proprietário, finalidade, escopos, data de expiração e integrações que dependem dele. Substitua os PATs antes de expirarem, com base na política da sua organização e no risco envolvido no cenário.

Recuperar após a expiração ou revogação

Se um PAT parar de funcionar inesperadamente:

1. Na página Tokens de acesso pessoal , verifique o status e a expiração do PAT.
2. Crie um PAT de substituição com apenas os escopos exigidos pelas integrações afetadas.
3. Atualize as integrações que armazenam o PAT indisponível.
4. Teste cada integração e monitore sua próxima operação agendada para falhas de autenticação.

Se o motivo da falha não estiver claro, examine os eventos de auditoria do PAT para determinar se o PAT expirou, foi atualizado ou foi revogado.

Gerenciar PATs com as APIs de Gerenciamento de Ciclo de Vida

Use as APIs de Gerenciamento de Ciclo de Vida do PAT para listar, criar, atualizar e revogar seus próprios PATs programaticamente.

Essas APIs exigem um token de acesso do Microsoft Entra de um fluxo delegado pelo usuário. Utilize o escopo vso.pats. Entidades de serviço e identidades gerenciadas não podem criar ou gerenciar PATs porque não representam um usuário.

Operação	Solicitação
Lista de PATs	GET https://vssps.dev.azure.com/{organization}/_apis/tokens/pats?api-version=7.1
Criar um PAT	POST https://vssps.dev.azure.com/{organization}/_apis/tokens/pats?api-version=7.1
Revogar um PAT	DELETE https://vssps.dev.azure.com/{organization}/_apis/tokens/pats?authorizationId={authorizationId}&api-version=7.1

Envie o token Microsoft Entra como um token de portador. Uma solicitação de criação usa o seguinte formato de corpo:

{
  "displayName": "CI build access",
  "scope": "vso.build",
  "validTo": "{expiration-in-UTC}",
  "allOrgs": false
}

A resposta da lista retorna tokens na patTokens matriz. Uma resposta de criação retorna o segredo uma vez em patToken.token. Armazene esse valor com segurança e nunca o escreva em logs. Para revogar o token antigo, passe-o authorizationId como o parâmetro de consulta mostrado na tabela.

Para obter esquemas e exemplos completos, consulte Listar PATs, Criar um PAT e revogar um PAT.

Examinar eventos de auditoria do PAT

O Azure DevOps Services registra eventos do ciclo de vida do PAT no log de auditoria da organização. Nas configurações da Organização, selecione Auditoria e, em seguida, filtre para estas ações:

Action	Event
Um PAT é criado	Token.PatCreateEvent
Um PAT expira	Token.PatExpiredEvent
Um PAT é encontrado em um repositório público	Token.PatPublicDiscoveryEvent
Um usuário revoga um PAT	Token.PatRevokeEvent
Azure DevOps revoga um PAT	Token.PatSystemRevokeEvent
Um PAT é modificado ou regenerado	Token.PatUpdateEvent

Os eventos de acesso ao token não são registrados no momento. Use o log de auditoria para investigar as alterações do ciclo de vida, não para determinar quando ou se um PAT foi usado.

Retenção de log de auditoria

Os eventos de auditoria são mantidos por 90 dias e excluídos. O período de retenção não é configurável. Para reter eventos por mais tempo, exporte-os para CSV ou JSON ou configure um fluxo de auditoria para um sistema de SIEM (gerenciamento de eventos e informações de segurança externo).

Para obter mais informações, consulte Acessar, exportar e filtrar logs de auditoria e Eventos de auditoria do Azure DevOps.

Configurar políticas de PAT

Os administradores de locatários podem restringir PATs globais e PATs de escopo completo, definir um tempo de vida máximo do PAT e controlar a revogação automática de PATs vazados. Configurar políticas de PAT no nível do locatário em Configurações da organização> no Microsoft Entra.

Os proprietários da organização podem restringir a criação de PAT para uma organização específica em Configurações da organização>. Para funções, comportamento de política e procedimentos de lista de permissões, consulte Gerenciar PATs com políticas.

Formato PAT

As cadeias PAT usam um formato identificável que melhora a detecção de segredos e reduz falsos positivos.

• PaTs têm 84 caracteres, incluindo 52 caracteres aleatórios.
• Azure DevOps PATs contêm a assinatura fixa AZDO nas posições 76 a 80.

Se sua integração validar PATs, dê suporte ao formato de 84 caracteres. Para controles de tokens vazados, consulte Revogar PATs vazados automaticamente.

Práticas recomendadas para usar PATs

Alternativas a serem consideradas

• Use Microsoft Entra tokens para aplicativos e automação.
• Para comandos únicos, adquira um token Microsoft Entra por meio do CLI do Azure.
• Para Git, use Git Credential Manager. Para Azure Artifacts, use o provedor de credenciais Azure Artifacts.

Criar PATs

• Crie apenas PATs com escopo organizacional. As PATs globais param de funcionar em 1º de dezembro de 2026.
• Use um PAT diferente para cada ferramenta ou fluxo de trabalho.
• Selecione apenas os escopos necessários para a tarefa.
• Mantenha o tempo de vida tão curto quanto prático.
• Não inclua dados pessoais ou qualquer parte do valor do token em seu nome de exibição.

Gerenciar PATs

• Não compartilhe PATs.
• Armazene PATs em um repositório de segredos seguro, como Azure Key Vault.
• Substitua os PATs antes de expirarem e revogue-os quando eles não forem mais necessários.
• Revogue um PAT imediatamente se ele estiver exposto ou comprometido.

Para administradores

• Restrinja PATs de escopo completo e defina um tempo de vida máximo com base em seus requisitos de segurança.
• Restrinja a criação de PAT em organizações que não exigem isso.
• Use as APIs de Administração de Token compatíveis para revogar PATs de usuários.
• Prefira a autenticação do Microsoft Entra para serviços e automação.

Examinar e responder a PATs de risco

Como parte de sua revisão de segurança:

1. Identifique PATs com todos os escopos, longa duração, acesso global ou sem proprietário e propósito documentados.
2. Examine os eventos de criação, atualização, descoberta pública, expiração e revogação do PAT no log de auditoria. Como o acesso a tokens não é registrado, não use o log de auditoria para classificar um PAT como ativo ou obsoleto.
3. Revogar PATs expostas, comprometidas ou desnecessárias. Para o desligamento, use as APIs de Administração de Token compatíveis para revogar os PATs do usuário e notificar os proprietários das integrações afetadas.
4. Configure políticas de PAT de locatário e organização para restringir PATs globais e de escopo completo, definir o tempo de vida máximo e controlar a revogação automática de PATs vazados.
5. Exporte eventos de auditoria ou configure um fluxo de auditoria quando seus requisitos de retenção excederem 90 dias.

Perguntas Frequentes

Por que não posso editar ou regenerar um PAT com escopo em uma única organização?

Faça login na organização à qual o PAT está vinculado. Você pode listar seus PATs de qualquer organização no mesmo locatário do Microsoft Entra alterando o filtro Escopo de acesso, mas só pode editar um PAT com escopo de organização nessa organização.

O que acontece com PATs quando uma conta de usuário é desabilitada?

Quando uma conta é desabilitada ou removida de uma organização, seus PATs não podem mais acessar os recursos dessa organização. Azure DevOps não exclui automaticamente os PATs. Se o acesso for restaurado, um PAT que não expirou ou foi revogado funcionará com as permissões atuais do usuário.

Posso usar PATs com todas as APIs REST Azure DevOps?

Não. Os PATs funcionam com a maioria das APIs REST Azure DevOps. Algumas APIs, incluindo organizações, perfis e APIs de Gerenciamento de Ciclo de Vida do PAT, exigem tokens de Microsoft Entra.

O que acontece se eu confirmar um PAT em um repositório de GitHub público?

Azure DevOps verifica repositórios de GitHub públicos para PATs vazadas. Quando ele detecta um token, Azure DevOps notifica o proprietário e registra um evento de auditoria. A menos que a política de locatário desabilite a revogação automática, Azure DevOps revoga o PAT vazado. Para obter mais informações, consulte Revogar automaticamente PATs vazados.

Posso usar um PAT como uma chave de API para publicar pacotes NuGet?

Não. Azure Artifacts não dá suporte à passagem de um PAT como uma chave de API. Em um ambiente de desenvolvimento local, instale o provedor de credenciais Azure Artifacts. No Azure Pipelines, use a tarefa Autenticação do NuGet.

Para obter exemplos, consulte Publicar com dotnet, Publicar com NuGet.exee Publicar pacotes NuGet com Azure Pipelines.

Por que meu PAT parou de funcionar?

Verifique se o PAT expirou, foi revogado, ficou inativo, tem escopos insuficientes ou pertence a um usuário cujas permissões foram alteradas. Para uma organização apoiada por Microsoft Entra ID, entre no Azure DevOps e conclua o prompt de autenticação completo e tente novamente. Sua configuração de Acesso Condicional pode exigir uma entrada mais frequente.

No Azure DevOps Server, a Autenticação Básica do IIS impede a autenticação de PAT. Mantenha a Autenticação Básica do IIS desabilitada.

Como criar um token de acesso que não esteja vinculado a um usuário?

Os PATs são sempre associados ao usuário que os criou. Para uma identidade que não seja de usuário, use um token do Microsoft Entra emitido para uma entidade de serviço de aplicativo ou identidade gerenciada. Para pipelines, use uma conexão de serviço.

Como fazer para girar um PAT por meio da API?

As APIs de Gerenciamento do Ciclo de Vida não regeneram um PAT em uma operação. Liste o PAT antigo para obter seus metadados, crie um PAT com o escopo e a expiração necessários, atualize e teste cada integração dependente e, em seguida, revogue o PAT antigo usando seu authorizationId. Para obter as rotas corretas, consulte Gerenciar PATs com as APIs de Gerenciamento de Ciclo de Vida.

Por que uma mensagem de aprovação de administrador aparece quando chamo as APIs de Gerenciamento do Ciclo de Vida do PAT?

As políticas de segurança do locatário exigem o consentimento do administrador antes que o aplicativo Microsoft Entra possa acessar os recursos da organização. Contate o administrador do locatário.

Artigos relacionados

• Diretrizes de autenticação
• Autenticar usando tokens do Microsoft Entra
• Usar entidades de serviço e identidades gerenciadas
• Gerenciar PATs com políticas
• Revogar PATs de usuário.