Compartilhar via

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

  • Artigo

Azure DevOps Services

Quando você está lidando com um grande conjunto de PATs (tokens de acesso pessoal) que 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 seus PATs, permitindo que você crie novos PATs e renove ou expire PATs existentes.

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

Pré-requisitos

  • Permissões: dependendo das políticas de segurança do locatário, seu aplicativo pode precisar de permissões para acessar recursos na organização. Neste momento, a única maneira de continuar com o uso desse aplicativo nesse locatário é pedir a um administrador que conceda permissão ao aplicativo antes que você possa usá-lo.

Observação

Você não pode usar entidades de serviço ou identidades gerenciadas para criar ou revogar PATs.

Autenticar com tokens do Microsoft Entra

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

Para adquirir e atualizar tokens de acesso do Microsoft Entra, execute as seguintes tarefas:

Importante

As soluções de "aplicativo em nome de" (como o fluxo de "credencial do 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".

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

Para chamar a API diretamente, forneça um token de acesso do Microsoft Entra como um Bearer token no Authorization cabeçalho da solicitação. Para obter mais informações 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. O aplicativo usa a biblioteca MSAL (Biblioteca de Autenticação da Microsoft) e chama nossa API de Gerenciamento do Ciclo de Vida do PAT.

A 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 da MSAL pode ser encontrada na documentação de 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.

Para começar, consulte um dos seguintes exemplos:

Clone nosso aplicativo da web Python Flask

Fornecemos um aplicativo Web Python Flask de exemplo 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 autenticação MSAL para adquirir um token de acesso do Microsoft Entra.

Importante

Recomendamos começar a usar 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 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 repositório. O LEIAME 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 de início rápido 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 precisam atualizar a configuração do aplicativo para apontar para o endpoint da API de gerenciamento do ciclo de vida do 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 de documentos de desenvolvimento de ID do Microsoft Entra. Percorremos o exemplo a seguir com um aplicativo de início rápido do Python Flask.

Exemplo: Introdução a um aplicativo de início rápido do Python Flask

  1. 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 ID do Microsoft Entra –> Registros de Aplicativo no portal do Azure.

    A captura de tela mostra o Microsoft Entra ID aberto, Registros de aplicativos.

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

    A captura de tela mostra a seleção de um aplicativo e a navegação até as permissões da API.

  3. Selecione Adicionar uma permissão e selecione Azure DevOps –> verificar user_impersonation –> selecione Adicionar permissões.

    A captura de tela mostra adicionar o Azure DevOps, user_impersonation permissão.

  4. Selecione Início Rápido.

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

  6. Selecione sua plataforma de aplicativo. 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. A URL de resposta é a URL de redirecionamento que foi definida na criação do aplicativo + "/getAToken".

    A captura de tela mostra permitindo que o portal do Azure faça as alterações necessárias para configurar seu aplicativo.

  8. Baixe o aplicativo Quickstart e extraia os arquivos.

    A captura de tela mostra o download do aplicativo Quickstart e a extração dos arquivos.

  9. Instale os requisitos do aplicativo e execute o aplicativo para garantir que você tenha todas as dependências necessárias. O aplicativo é configurado inicialmente para atingir um ponto de extremidade na API do Microsoft Graph. Saiba como alterar esse endpoint para o endpoint base da API PAT Lifecycle Management seguindo as instruções de configuração na seção a seguir.

    A captura de tela mostra a instalação dos requisitos do aplicativo e a execução do aplicativo.

Configurar um aplicativo de início rápido

Depois que o usuário baixa e instala o aplicativo de Início Rápido, ele é configurado para usar um ponto de extremidade de API de teste do Microsoft Graph. Modifique o arquivo de configuração gerado para que ele chame a API de gerenciamento do ciclo de vida do PAT.

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.

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 de gerenciamento do ciclo de vida do PAT
  2. Atualize a variável de configuração SCOPE para "499b84ac-1321-427f-aa17-267ca6975798/.default" para se referir ao recurso do Azure DevOps e a todos os seus escopos.

O exemplo a seguir mostra como fizemos essa configuração para o aplicativo Flask Python de Início Rápido 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 for usado na produção. As instruções para usar um certificado podem ser encontradas na etapa final da configuração do aplicativo Quickstart.

Cuidado

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

Exemplo: configurar um aplicativo de início rápido do Python Flask para a API de gerenciamento do ciclo de vida do PAT

  1. Depois de baixar seu aplicativo de início rápido, 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 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

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

  3. Altere a variável para a URL de coleção do Azure DevOps e o ENDPOINT 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 do Azure DevOps; a cadeia de caracteres é a ID do recurso para a API do Azure DevOps e o .default escopo refere-se a todos os escopos dessa ID de recurso.

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

  5. Se o 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 de locatário e URL de coleção. 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. Depois de verificado, você pode modificar o conteúdo e o 'ms-identity-python-webapp-master\templates' diretório para oferecer suporte ao envio de 'app.py' solicitações para o restante dos endpoints da API de gerenciamento do ciclo de vida do PAT. Para obter um exemplo de um aplicativo de início rápido do Python Flask que foi modificado para dar 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

Depois que o aplicativo estiver configurado corretamente e o usuário adquirir um token de acesso, o token poderá ser usado por até uma hora. O código MSAL fornecido em ambos os exemplos anteriores atualiza automaticamente o token quando ele expira. A atualização do token impede 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 após a expiração do token de atualização.

Explore as APIs de gerenciamento do ciclo de vida do PAT

No aplicativo de exemplo GitHub anterior e nos aplicativos de início rápido, o aplicativo é pré-configurado para fazer solicitações com os tokens do Microsoft Entra que você adquiriu. Para obter mais informações, consulte os documentos de referência da API.

Perguntas frequentes (FAQs)

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 PATs existentes. Nas mãos erradas, agentes mal-intencionados podem usar essa API para criar vários pontos de entrada nos recursos do Azure DevOps da sua organização. Ao impor a autenticação do Microsoft Entra, esperamos que essa API poderosa 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 desse 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 um pedido de exemplo, acesse 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 poderemos analisá-lo nesses documentos de forma mais ampla!

P: Qual é a diferença entre essa API de token e a API de administração 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-alvo:

  • Essa API de token é em grande parte para usuários que desejam gerenciar os PATs que possuem em um pipeline automatizado. Esta API permite. Dá a você 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 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: Ó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, execute as seguintes etapas:

  1. Entenda os metadados do PAT usando uma chamada GET ,
  2. Crie um novo PAT com os metadados do PAT antigo usando uma chamada POST ,
  3. Revogue o PAT antigo usando uma chamada DELETE

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

R: 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 continuar com o uso desse aplicativo nesse locatário é pedir a um administrador que conceda permissão ao aplicativo antes que você possa usá-lo.

P: Por que estou vendo 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 gerenciamento do ciclo de vida do PAT usando uma entidade de serviço ou identidade gerenciada?

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

Próximas etapas

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