Gerenciar tokens de acesso pessoal (PATs) usando a API REST

Artigo
10/23/2023

Azure DevOps Services

Quando você está lidando com um grande conjunto de tokens de acesso pessoal (PATs) que você possui, pode se tornar complexo gerenciar a manutenção desses tokens usando apenas a interface do usuário.

Com a API de Gerenciamento do Ciclo de Vida de PAT, é possível gerenciar facilmente os PATs associados às suas organizações usando processos automatizados. Esse rico conjunto de APIs permite que você gerencie os PATs que você possui, permitindo que você crie novos tokens de acesso pessoal e renove ou expire tokens de acesso pessoal existentes.

Neste artigo, mostraremos como configurar um aplicativo que se autentica com um token do Microsoft Entra e faz chamadas com a API do ciclo de vida do PAT. Para ver apenas a lista completa de pontos de extremidade disponíveis, exiba aqui a referência da API.

Pré-requisitos

Para usar a API, você deve autenticar com um token Microsoft Entra, o que pode ser feito via Microsoft Entra ID OAuth. Saiba mais sobre como fazer isso na seção de autenticação a seguir.

Para isso, alguns pré-requisitos devem ser atendidos:

Você deve ter um locatário do Microsoft Entra com uma assinatura ativa do Azure.
Dependendo das políticas de segurança do locatário, talvez seja necessário conceder permissões ao aplicativo para acessar recursos na organização. Neste momento, a única maneira de continuar com o uso deste aplicativo neste locatário é pedir a um administrador para conceder permissão ao aplicativo antes que você possa usá-lo.

Autenticar com tokens do Microsoft Entra

Ao contrário de outras APIs dos Serviços de DevOps do Azure, os usuários devem fornecer um token de acesso do Microsoft Entra para usar essa API em vez de um token PAT. Os tokens do Microsoft Entra são um mecanismo de autenticação mais seguro do que o uso de PATs. Dada a capacidade dessa API de criar e revogar PATs, queremos garantir que essa funcionalidade poderosa seja dada apenas aos usuários permitidos.

Para adquirir e atualizar tokens de acesso do Microsoft Entra, você deve:

Importante

Soluções "em nome do aplicativo" (como o fluxo de "credenciais do cliente") e qualquer fluxo de autenticação que não emita um token de acesso do Microsoft Entra não é válido para uso com essa API. Se a autenticação multifator estiver habilitada em seu locatário do Microsoft Entra, você deverá definitivamente usar o fluxo de "código de autorização".

Cuidado

Ter um locatário do Microsoft Entra com uma assinatura ativa do Azure é um pré-requisito para usar essa API.

Depois de ter um aplicativo com um fluxo de autenticação funcional para manipular tokens do Microsoft Entra, você poderá usar esses tokens para fazer chamadas para a API do PAT Lifecycle Management.

Para chamar a API diretamente, você precisa fornecer um token de acesso do Microsoft Entra como um Bearer token no Authorization cabeçalho de sua solicitação. Para ver os exemplos e uma lista completa das solicitações disponíveis, consulte a referência da API PAT

Na seção a seguir, mostramos como criar um aplicativo que autentica um usuário com um token de acesso do Microsoft Entra usando a biblioteca MSAL e chama nossa API de Gerenciamento do Ciclo de Vida do PAT.

A Biblioteca de Autenticação da Microsoft (MSAL) inclui vários fluxos de autenticação compatíveis que você pode usar em seu aplicativo para adquirir e atualizar tokens do Microsoft Entra. Uma lista completa de fluxos MSAL pode ser encontrada na documentação "fluxos de autenticação" da Biblioteca de Autenticação da Microsoft. Um guia para escolher o método de autenticação correto para seu aplicativo pode ser encontrado em Escolhendo o método de autenticação correto para o Azure DevOps.

Siga um dos dois exemplos para começar:

Clone nosso aplicativo Python Flask de exemplo e configure-o com seu locatário e organização ADO
Gere um aplicativo de exemplo no portal do Azure para o idioma de sua escolha e configure-o para a API de Gerenciamento do Ciclo de Vida do PAT

Clone nosso aplicativo web Python Flask

Fornecemos um aplicativo Web Python Flask de exemplo para essa API que você pode baixar no GitHub e pode ser configurado para uso com seu locatário do Microsoft Entra e sua organização do Azure DevOps. O aplicativo de exemplo usa o fluxo de código de autenticação MSAL para adquirir um token de acesso do Microsoft Entra.

Importante

Recomendamos começar com o aplicativo Web Python Flask de exemplo no GitHub, mas se você preferir usar uma linguagem ou tipo de aplicativo diferente, use a opção Guia de início rápido para recriar um aplicativo de teste equivalente.

Depois de clonar o aplicativo de exemplo, siga as instruções no LEIA-ME do repositório. O LEIA-ME explica como registrar um aplicativo em seu locatário do Microsoft Entra, configurar o exemplo para usar seu locatário do Microsoft Entra e executar seu aplicativo clonado.

Gerar um aplicativo de portal do Azure de início rápido

Em vez disso, você pode gerar um aplicativo de exemplo com o código MSAL gerado usando a opção Guia de início rápido na página do aplicativo no portal do Azure. O aplicativo de teste Quickstart segue o fluxo de código de autorização, mas faz isso com um ponto de extremidade da API do Microsoft Graph. Os usuários precisarão atualizar a configuração do aplicativo para apontar para o ponto de extremidade da API do PAT Lifecycle Management.

Para seguir essa abordagem, siga as instruções de início rápido para o tipo de aplicativo de sua escolha na página inicial do Microsoft Entra ID Develop docs. Apresentaremos um exemplo em que fizemos isso para um aplicativo Python Flask Quickstart.

Exemplo: Introdução a um aplicativo Python Flask Quickstart

Depois de registrar seu aplicativo em um locatário do Microsoft Entra que tenha uma assinatura ativa do Azure, navegue até seu aplicativo registrado em Microsoft Entra ID ->App Registrations no portal do Azure.
Selecione seu aplicativo e navegue até Permissões de API.
Selecione Adicionar uma permissão e selecione Azure DevOps - marque user_impersonation ->> selecione Adicionar permissões.
Selecione Guia de início rápido no painel de navegação esquerdo.
Selecione o tipo de aplicativo: para Python Flask, selecione Aplicativo Web.
Selecione sua plataforma de aplicativo. Para este tutorial, selecione "Python".
Verifique se você atendeu aos pré-requisitos necessários e permita que o portal do Azure faça as alterações necessárias para configurar seu aplicativo. A URL de resposta será a URL de redirecionamento que foi definida na criação do aplicativo + "/getAToken".
Baixe o aplicativo Quickstart e extraia os arquivos.
Instale os requisitos do aplicativo e execute o aplicativo para garantir que você tenha todas as dependências necessárias. O aplicativo é inicialmente configurado para atingir um ponto de extremidade na API do Microsoft Graph. Saiba como alterar esse ponto de extremidade para o ponto de extremidade base da API do PAT Lifecycle Management seguindo as instruções de configuração na seção a seguir.

Configurar um aplicativo de início rápido

Depois que o usuário tiver baixado e instalado o aplicativo Quickstart, ele será configurado para usar um ponto de extremidade de API de teste do Microsoft Graph. Precisaremos modificar o arquivo de configuração gerado para que ele chame a API do PAT Lifecycle Management.

Dica

Usamos coleção e organização de forma intercambiável nesses documentos. Se uma variável de configuração precisar de um nome de coleção, substitua-a pelo nome da sua organização.

Para isso, precisamos fazer algumas coisas:

Atualize a variável de configuração ENDPOINT para https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview as APIs do PAT Lifecycle Management
Atualize a variável de configuração SCOPE para "499b84ac-1321-427f-aa17-267ca6975798/.default" para se referir ao recurso Azure DevOps e a todos os seus escopos.

O exemplo a seguir mostrará como fizemos essa configuração para o aplicativo Quickstart Python Flask que geramos por meio do portal do Azure na seção anterior.

Certifique-se de seguir as instruções para proteger o segredo do cliente, que é inicialmente inserido em texto sem formatação no arquivo de configuração do aplicativo. Como prática recomendada, remova a variável de texto sem formatação do arquivo de configuração e use uma variável de ambiente ou o Azure KeyVault para proteger o segredo do aplicativo.

Em vez disso, você pode optar por usar um certificado em vez de um segredo do cliente. O uso de certificados é a opção recomendada se o aplicativo eventualmente for usado na produção. As instruções para usar um certificado podem ser encontradas na etapa final da configuração do aplicativo Guia de início rápido.

Cuidado

Nunca deixe um segredo de cliente de texto simples no código do aplicativo de produção.

Exemplo: Configurar um aplicativo Python Flask Quickstart para a API de gerenciamento do ciclo de vida do PAT

Depois de baixar o aplicativo Quickstart, instalar suas dependências e testar que ele é executado em seu ambiente, abra o app_config.py arquivo no editor de sua escolha. O arquivo deve ser semelhante ao seguinte trecho de código; para maior clareza, os comentários referentes à configuração padrão da API do Microsoft Graph foram removidos:

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret,
# like Azure Key Vault. Or, use an environment variable as described in Flask's documentation:
# https://flask.palletsprojects.com/en/1.1.x/config/#configuring-from-environment-variables
# CLIENT_SECRET = os.getenv("CLIENT_SECRET")
# if not CLIENT_SECRET:
#     raise ValueError("Need to define CLIENT_SECRET environment variable")

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  

SCOPE = ["User.ReadBasic.All"]

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

Atualize a ID do cliente ou o segredo do cliente para seu aplicativo com a ID do cliente e o segredo do cliente do registro do aplicativo. Quando estiver em produção, certifique-se de proteger o segredo do cliente usando uma variável de ambiente, o Azure KeyVault, ou alternando para um certificado.
```
CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret.
```

Altere a ENDPOINT variável para a URL da coleção de DevOps do Azure e o ponto de extremidade da API. Por exemplo, para uma coleção chamada "testCollection", o valor seria:

# Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here

ENDPOINT = 'https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview'

Para uma coleção chamada "testCollection", esse ponto de extremidade seria:

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview'

Altere a variável para fazer referência ao recurso da API de DevOps do Azure: a cadeia de caracteres é a ID do recurso para a API de DevOps do Azure e o escopo ".default" refere-se a SCOPE todos os escopos dessa ID de recurso.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Se seu aplicativo estiver configurado para um locatário específico (em vez da configuração multilocatário), use o valor alternativo para a AUTHORITY variável, adicionando o nome do locatário específico em "Enter_the_Tenant_Name_Here".
```
# For single-tenant app:
AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"

# For multi-tenant app:
AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"
```

Verifique se o arquivo final app_config.py corresponde ao seguinte, com seu CLIENT_ID, ID do locatário e URL de coleta. Por motivos de segurança, verifique se o CLIENT_SECRET foi movido para uma variável de ambiente, o Azure KeyVault, ou trocado por um certificado para seu aplicativo registrado:

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

# Note that the CLIENT_SECRET has been removed and moved to an environment variable or Azure KeyVault

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set in the app's registration in the Azure portal.

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' 
# Used to configure user's collection URL and the desired API endpoint

SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
# Means "All scopes for the Azure DevOps API resource"

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

Execute novamente o aplicativo para testar se você pode OBTER todos os tokens PAT para o usuário solicitante. Depois de verificar isso, sinta-se à vontade para modificar o conteúdo e o diretório para oferecer suporte ao envio de solicitações para 'app.py' o 'ms-identity-python-webapp-master\templates' restante dos pontos de extremidade da API de gerenciamento do ciclo de vida do PAT. Para obter um exemplo de um aplicativo Python Flask Quickstart que foi modificado para oferecer suporte a solicitações para todos os pontos de extremidade da API de gerenciamento do ciclo de vida do PAT, consulte este repositório de exemplo no GitHub.

Atualizar automaticamente um token de acesso do Microsoft Entra

Uma vez que o aplicativo está configurado corretamente e o usuário adquiriu um token de acesso, o token pode ser usado por até uma hora. O código MSAL fornecido em ambos os exemplos acima atualizará automaticamente o token assim que ele expirar. A atualização do token evita que o usuário precise fazer login novamente e adquirir um novo código de autorização. No entanto, os usuários podem precisar fazer logon novamente após 90 dias, uma vez que seu token de atualização expira.

Explore as APIs de gerenciamento do ciclo de vida do PAT

No aplicativo de exemplo GitHub e nos aplicativos Quickstart acima, o aplicativo foi pré-configurado para fazer solicitações com os tokens do Microsoft Entra que você adquiriu. Para saber mais sobre os pontos de extremidade, quais parâmetros eles aceitam e o que é retornado em respostas, consulte os documentos de referência da API.

Perguntas frequentes

P: Por que preciso me autenticar com um token do Microsoft Entra? Por que um PAT não é suficiente?

R: Com essa API de gerenciamento do ciclo de vida do PAT, abrimos a capacidade de criar novos PATs e revogar os PATs existentes. Nas mãos erradas, essa API pode ser usada por agentes mal-intencionados para criar vários pontos de entrada nos recursos ADO da sua organização. Ao impor a autenticação do Microsoft Entra, esperamos que essa poderosa API seja mais segura contra esse uso não autorizado.

P: Preciso ter um locatário do Microsoft Entra com uma assinatura ativa do Azure para usar essa API?

R: Infelizmente, essa API só está disponível para usuários que fazem parte de um locatário do Microsoft Entra com uma assinatura ativa do Azure.

P: Posso obter um exemplo deste aplicativo de exemplo para outro tipo de linguagem/estrutura/aplicativo?

R: Adoramos que você queira usar a API no idioma de sua escolha! Se você tiver uma solicitação de exemplo, vá até nossa Comunidade de Desenvolvedores para ver se alguém tem um exemplo para compartilhar. Se você tiver um aplicativo de exemplo que gostaria de compartilhar com o público maior do Azure DevOps, informe-nos e podemos analisá-lo nesses documentos mais amplamente!

P: Qual é a diferença entre essa API de token e a API de administrador de token?

R: ESSA API DE TOKEN E A API DE ADMINISTRAÇÃO DE TOKEN, EMBORA SEMELHANTES, ATENDEM A DIFERENTES CASOS DE USO E PÚBLICOS:

Essa API de token é em grande parte para usuários que desejam gerenciar os PATs que possuem em um pipeline automatizado. Esta API permite. Ele lhe dá a capacidade de criar novos tokens e atualizar os existentes.
A API de administração de token destina-se a administradores de organização. Os administradores podem usar essa API para recuperar e revogar autorizações OAuth, incluindo tokens de acesso pessoal (PATs) e tokens de sessão autodescritivos, de usuários em suas organizações.

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

R: Ótima pergunta! A funcionalidade "Regenerar" disponível na interface do usuário realmente realiza algumas ações, que são totalmente replicáveis por meio da API.

Para girar seu PAT, você precisa:

Compreender os metadados do PAT usando uma chamada GET ,
Criar um novo PAT com os metadados do PAT antigo usando uma chamada POST ,
Revogar o PAT antigo usando uma chamada DELETE

P: Vejo um pop-up "Precisa de aprovação do administrador" quando tento continuar com o uso deste aplicativo. Como posso usar este aplicativo sem a aprovação do administrador?

R: Parece que seu locatário definiu políticas de segurança que exigem que seu aplicativo receba permissões para acessar recursos na organização. Neste momento, a única maneira de continuar com o uso deste aplicativo neste locatário é pedir a um administrador para conceder permissão ao aplicativo antes que você possa usá-lo.

Próximas etapas

Saiba mais sobre os pontos de extremidade da API de gerenciamento do ciclo de vida do PAT