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

Artigo
10/23/2023

Serviços de DevOps do Azure

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

Com a API de Gestão do Ciclo de Vida do PAT, pode gerir facilmente os PATs associados às suas organizações através de processos automatizados. Esse rico conjunto de APIs permite que você gerencie os PATs que 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 de ciclo de vida da PAT. Se quiser ver apenas a lista completa de pontos finais disponíveis, veja a referência da API aqui.

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 tal, devem ser cumpridos alguns pré-requisitos:

Você deve ter um locatário do Microsoft Entra com uma assinatura ativa do Azure.
Dependendo das políticas de segurança do seu locatário, seu aplicativo pode precisar receber permissões para acessar recursos na organização. Neste momento, a única maneira de prosseguir 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 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 Microsoft Entra são um mecanismo de autenticação mais seguro do que usar PATs. Dada a capacidade desta API de criar e revogar PATs, queremos garantir que essa funcionalidade poderosa seja dada apenas a usuários permitidos.

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

Importante

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

Atenção

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 lidar com tokens do Microsoft Entra, você pode usar esses tokens para fazer chamadas para a API de Gerenciamento do Ciclo de Vida da PAT.

Para chamar a API diretamente, você precisa fornecer um token de acesso do Microsoft Entra como um Bearer token no Authorization cabeçalho da sua solicitação. Para ver os exemplos e uma lista completa dos pedidos 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 da 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 dos 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 certo para seu aplicativo pode ser encontrado em Escolhendo o método de autenticação certo 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 uma aplicação de exemplo no portal do Azure para o idioma da sua escolha e configure-a para a API de Gestão do Ciclo de Vida da PAT

Clone nosso aplicativo web Python Flask

Fornecemos um exemplo de aplicativo Web Python Flask para essa API que você pode baixar no GitHub e pode ser configurado para usar com seu locatário do Microsoft Entra e a 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 README do repo. 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 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 utilizadores terão de atualizar a configuração da aplicação para apontar para o ponto de extremidade da API de Gestão do Ciclo de Vida da PAT.

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. Vamos percorrer um exemplo onde 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 ->Registros de aplicativos 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 seu tipo de aplicativo: para Python Flask, selecione Aplicativo Web.
Selecione a sua plataforma de aplicação. 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. O URL de resposta será o URL de redirecionamento que foi definido 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 este ponto de extremidade para o ponto de extremidade base da API de Gestão do Ciclo de Vida da PAT seguindo as instruções de configuração na secção seguinte.

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. Em vez disso, teremos de modificar o ficheiro de configuração gerado para que este chame a API de Gestão do Ciclo de Vida da PAT.

Gorjeta

Utilizamos a recolha e a organização de forma intercambiável nestes 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 fazer referência ao recurso DevOps do Azure e 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 simples 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 for eventualmente usado na produção. As instruções para usar um certificado podem ser encontradas na etapa final da configuração do aplicativo Quickstart.

Atenção

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

Exemplo: Configurar uma aplicação Python Flask Quickstart para a API de gestão do ciclo de vida da PAT

Depois de baixar seu 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 que fazem referência à 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, 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 variável para a ENDPOINT URL da coleção do Azure DevOps 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 que tem, sinta-se à vontade para modificar o conteúdo 'app.py' e o 'ms-identity-python-webapp-master\templates' diretório para dar suporte ao envio de solicitações para o restante dos pontos de extremidade da API de gerenciamento do ciclo de vida da PAT. Para obter um exemplo de um aplicativo Python Flask Quickstart que foi modificado para suportar solicitações para todos os pontos de extremidade da API de gerenciamento do ciclo de vida da PAT, consulte este repositório de exemplo no GitHub.

Atualizar automaticamente um token de acesso do Microsoft Entra

Uma vez que o aplicativo esteja configurado corretamente e o usuário tenha adquirido 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 login novamente após 90 dias, quando o token de atualização expirar.

Explore as APIs de Gestão do Ciclo de Vida da PAT

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

FAQ

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

R: Com esta API de Gestão do Ciclo de Vida da PAT, abrimos a capacidade de criar novos PATs e revogar os PATs existentes. Nas mãos erradas, essa API pode ser usada por atores 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: Nós adoramos que você queira usar a API no idioma de sua escolha! Se você tiver uma solicitação para um exemplo, vá até nossa Comunidade de Desenvolvimento 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 analisar como divulgá-lo nesses documentos mais amplamente!

P: Qual é a diferença entre esta API de token e a API de administração de token?

R: Esta API de token e a API de administração de token, embora semelhantes, servem 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 da 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 através da API? Eu 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 o seu PAT, você precisa:

Compreender os metadados da PAT utilizando uma chamada GET ,
Criar uma nova PAT com os metadados do PAT antigo usando uma chamada POST ,
Revogar a PAT antiga usando uma chamada DELETE

P: Vejo um pop-up "Precisa de aprovação do administrador" quando tento continuar a usar este 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 prosseguir 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óximos passos

Saiba mais sobre os endpoints da API de gestão do ciclo de vida da PAT