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

Serviços de DevOps do Azure

Quando se lida com um grande conjunto de tokens de acesso pessoal (PATs) que possui, pode se tornar complexo gerir a manutenção desses tokens usando apenas a UI.

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. Este rico conjunto de APIs permite gerenciar seus PATs, permitindo que você crie novos PATs e renove ou expire PATs existentes.

Neste artigo, mostramos como configurar um aplicativo que autentica com um token do Microsoft Entra e faz chamadas com a API de ciclo de vida da PAT.

Pré-requisitos

Ao contrário de outras APIs de Serviços de DevOps do Azure, os usuários devem fornecer um token de acesso Microsoft Entra usar essa API. Dada a capacidade desta API de criar e revogar PATs, queremos garantir que essa funcionalidade poderosa esteja disponível apenas para tokens Microsoft Entra mais seguros.

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

• Ter um locatário do Microsoft Entra com uma assinatura ativa do Azure
• Registrar um aplicativo em seu locatário do Microsoft Entra
• Adicionar permissões do Azure DevOps ao aplicativo
• Obter consentimento do administrador do locatário: dependendo das políticas de segurança do locatário, seu aplicativo pode precisar de permissões para acessar recursos na organização. Solicite a um administrador de locatário que conceda permissão ao aplicativo para usá-lo em seu locatário.

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, forneça um token de acesso do Microsoft Entra como um Bearer token no Authorization cabeçalho da sua solicitação. Para obter mais informações 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. A aplicação utiliza a biblioteca de autenticação da Microsoft (MSAL) e chama a nossa 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 configurar 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 autorização MSAL para adquirir um token de acesso do Microsoft Entra.

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 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 têm 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. Percorremos o exemplo a seguir com um aplicativo Python Flask Quickstart.

1. Depois de registar a sua aplicação num inquilino Microsoft Entra com uma subscrição ativa do Azure, navegue para a sua aplicação registada em Microsoft Entra ID ->Registos de Aplicação no portal do Azure.

   

2. Selecione seu aplicativo e navegue até Permissões de API.

   

3. Selecione Adicionar uma permissão e selecione Azure DevOps -> selecione os escopos apropriados de que necessita. Neste caso, as APIs de Gestão do Ciclo de Vida da PAT suportam apenas user_impersonation, mas outras APIs podem solicitar mais âmbitos granulares diferentes que pode encontrar na página de referência de cada API individualmente . Quando todos os escopos estiverem selecionados, clique em Adicionar permissões .

   

4. Selecione Guia de início rápido.

5. Selecione seu tipo de aplicativo: para Python Flask, selecione Aplicativo Web.

6. Selecione a sua plataforma de aplicação. Para este tutorial, selecione Python.

7. Certifique-se de atender aos pré-requisitos necessários e, em seguida, permita que o portal do Azure faça as alterações necessárias para configurar seu aplicativo. O URL de resposta é o URL de redirecionamento que foi definido na criação do aplicativo + "/getAToken".

   

8. Baixe o aplicativo Quickstart e extraia os arquivos.

   

9. 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 baixa e instala o aplicativo Quickstart, ele é configurado para usar um ponto de extremidade de API de teste do Microsoft Graph. Modifique o ficheiro de configuração gerado para que chame a API de Gestão do Ciclo de Vida da PAT.

Execute as seguintes tarefas:

1. 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
2. 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 mostra 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 usado na produção. As instruções para usar um certificado podem ser encontradas na etapa final da configuração do aplicativo Quickstart.

1. Depois de baixar seu aplicativo Quickstart, instalar suas dependências e testar se 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 faziam 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
   

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

3. Altere a ENDPOINT variável para a 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'
   

4. Altere a SCOPE 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 .default escopo se refere a todos os escopos dessa ID de recurso.

   SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
   

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

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

7. Execute novamente o aplicativo para testar se você pode OBTER todos os tokens PAT para o usuário solicitante. Uma vez verificado, pode modificar o conteúdo 'app.py' e o 'ms-identity-python-webapp-master\templates' diretório para suportar o envio de pedidos para o resto dos pontos finais da API de gestão 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 é 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 anteriores atualiza automaticamente o token assim que ele expira. A atualização do token evita que o usuário precise entrar novamente e adquirir um novo código de autorização. No entanto, os usuários podem precisar entrar novamente após 90 dias, quando o token de atualização expirar.

Perguntas mais frequentes (FAQ)

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

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?

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

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, siga os seguintes passos:

1. Compreender os metadados da PAT utilizando uma chamada GET ,
2. Criar uma nova PAT com os metadados do PAT antigo usando uma chamada POST ,
3. 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?

Parece que seu locatário tem 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.

P: Porque é que estou a ver um erro como "As entidades de serviço não têm permissão para executar esta ação" quando tento chamar a API de Gestão do Ciclo de Vida da PAT utilizando uma Entidade de Serviço ou uma Identidade Gerida?

R: Entidades de serviço e identidades gerenciadas não são permitidas. Dada a capacidade desta API de criar e revogar PATs, queremos garantir que essa funcionalidade poderosa seja dada apenas a usuários permitidos.