Gérer des jetons d’accès personnels (PAT) à l’aide de l’API REST

Article
10/23/2023

Azure DevOps Services

Lorsque vous traitez d’un grand ensemble de jetons d’accès personnels (PAT) que vous possédez, il peut devenir complexe de gérer la maintenance de ces jetons à l’aide de l’interface utilisateur seule.

Avec l’API de gestion du cycle de vie PAT, vous pouvez facilement gérer les PAT associés à vos organisations à l’aide de processus automatisés. Cet ensemble complet d’API vous permet de gérer les PAT que vous possédez, ce qui vous permet de créer de nouveaux jetons d’accès personnels et de renouveler ou d’expirer des jetons d’accès personnels existants.

Dans cet article, nous allons vous montrer comment configurer une application qui s’authentifie avec un jeton Microsoft Entra et effectue des appels avec l’API de cycle de vie PAT. Si vous souhaitez simplement voir la liste complète des points de terminaison disponibles, consultez la référence d’API ici.

Prérequis

Pour utiliser l’API, vous devez vous authentifier avec un jeton Microsoft Entra, qui peut être effectué via l’ID OAuth Microsoft Entra. En savoir plus sur la procédure à suivre dans la section d’authentification suivante.

Pour ce faire, quelques conditions préalables doivent être remplies :

Vous devez disposer d’un locataire Microsoft Entra avec un abonnement Azure actif.
Selon les stratégies de sécurité de votre locataire, votre application peut avoir besoin d’autorisations pour accéder aux ressources de l’organisation. À ce stade, la seule façon de procéder à l’utilisation de cette application dans ce locataire consiste à demander à un administrateur d’accorder l’autorisation à l’application avant de pouvoir l’utiliser.

S’authentifier avec des jetons Microsoft Entra

Contrairement à d’autres API Azure DevOps Services, les utilisateurs doivent fournir un jeton d’accès Microsoft Entra pour utiliser cette API au lieu d’un jeton PAT. Les jetons Microsoft Entra sont un mécanisme d’authentification plus sûr que l’utilisation de PAT. Étant donné la capacité de cette API à créer et révoquer des PAT, nous voulons nous assurer que cette fonctionnalité puissante est donnée aux utilisateurs autorisés uniquement.

Pour acquérir et actualiser les jetons d’accès Microsoft Entra, vous devez :

Important

Solutions « Au nom de l’application » (par exemple, le flux d’informations d’identification du client) et tout flux d’authentification qui n’émet pas de jeton d’accès Microsoft Entra n’est pas valide pour une utilisation avec cette API. Si l’authentification multifacteur est activée dans votre locataire Microsoft Entra, vous devez certainement utiliser le flux « code d’autorisation ».

Attention

Le fait d’avoir un locataire Microsoft Entra avec un abonnement Azure actif est un prérequis pour l’utilisation de cette API.

Une fois que vous disposez d’une application avec un flux d’authentification opérationnel pour gérer les jetons Microsoft Entra, vous pouvez utiliser ces jetons pour effectuer des appels à l’API de gestion du cycle de vie PAT.

Pour appeler directement l’API, vous devez fournir un jeton d’accès Microsoft Entra en tant que Bearer jeton dans l’en-tête Authorization de votre demande. Pour afficher les exemples et une liste complète des demandes disponibles, reportez-vous à la référence de l’API PAT.

Dans la section suivante, nous vous montrons comment créer une application qui authentifie un utilisateur avec un jeton d’accès Microsoft Entra à l’aide de la bibliothèque MSAL et appelle notre API de gestion du cycle de vie PAT.

La bibliothèque d’authentification Microsoft (MSAL) inclut plusieurs flux d’authentification conformes que vous pouvez utiliser dans votre application pour acquérir et actualiser des jetons Microsoft Entra. Vous trouverez la liste complète des flux MSAL sous la documentation « Flux d’authentification » de la bibliothèque d’authentification Microsoft. Vous trouverez un guide pour choisir la méthode d’authentification appropriée pour votre application sous Choisir la méthode d’authentification appropriée pour Azure DevOps.

Suivez l’un des deux exemples pour commencer :

Clonez notre exemple d’application Python Flask et configurez-la avec votre locataire et votre organisation ADO
Générez un exemple d’application dans l’Portail Azure pour votre langue de choix et configurez-la pour l’API de gestion du cycle de vie PAT

Cloner notre application web Python Flask

Nous vous avons fourni un exemple d’application web Python Flask pour cette API que vous pouvez télécharger sur GitHub et que vous pouvez configurer pour l’utiliser avec votre locataire Microsoft Entra et votre organisation Azure DevOps. L’exemple d’application utilise le flux de code d’authentification MSAL pour acquérir un jeton d’accès Microsoft Entra.

Important

Nous vous recommandons de commencer à utiliser l’exemple d’application web Python Flask sur GitHub, mais si vous préférez utiliser un autre langage ou type d’application, utilisez l’option Démarrage rapide pour recréer une application de test équivalente.

Une fois que vous avez cloné l’exemple d’application, suivez les instructions du fichier README du dépôt. Le fichier README explique comment inscrire une application dans votre locataire Microsoft Entra, configurer l’exemple pour utiliser votre locataire Microsoft Entra et exécuter votre application cloné.

Générer une application de démarrage rapide Portail Azure

Au lieu de cela, vous pouvez générer un exemple d’application avec le code MSAL généré à l’aide de l’option Démarrage rapide sur la page de l’application dans Portail Azure. L’application de test de démarrage rapide suit le flux de code d’autorisation, mais elle le fait avec un point de terminaison d’API Microsoft Graph. Les utilisateurs devront mettre à jour la configuration de l’application pour qu’elle pointe vers le point de terminaison de l’API de gestion du cycle de vie PAT.

Pour suivre cette approche, suivez les instructions de démarrage rapide pour le type d’application de votre choix sur la page d’accueil développement de l’ID Microsoft Entra. Nous allons parcourir un exemple dans lequel nous avons effectué cette opération pour une application de démarrage rapide Python Flask.

Exemple : Prise en main d’une application de démarrage rapide Python Flask

Une fois que vous avez inscrit votre application dans un locataire Microsoft Entra disposant d’un abonnement Azure actif, accédez à votre application inscrite sous Microsoft Entra ID ->Inscriptions d’applications dans le Portail Azure.
Sélectionnez votre application et accédez aux autorisations d’API.
Sélectionnez Ajouter une autorisation et sélectionnez Azure DevOps -> case activée user_impersonation -> sélectionnez Ajouter des autorisations.
Sélectionnez Démarrage rapide dans le volet de navigation gauche.
Sélectionnez votre type d’application : pour Python Flask, sélectionnez application web.
Sélectionnez votre plateforme d’application. Pour ce tutoriel, sélectionnez « Python ».
Vérifiez que vous avez rempli les conditions préalables nécessaires, puis autorisez Portail Azure à apporter les modifications nécessaires pour configurer votre application. L’URL de réponse est l’URL de redirection définie lors de la création de l’application + « /getAToken ».
Téléchargez l’application de démarrage rapide et extrayez les fichiers.
Installez les exigences de l’application et exécutez l’application pour vous assurer que vous disposez de toutes les dépendances nécessaires. L’application est initialement configurée pour atteindre un point de terminaison dans l’API Microsoft Graph. Découvrez comment remplacer ce point de terminaison par le point de terminaison de base de l’API de gestion du cycle de vie PAT en suivant les instructions de configuration de la section suivante.

Configurer une application de démarrage rapide

Une fois que l’utilisateur a téléchargé et installé l’application de démarrage rapide, il est configuré pour utiliser un point de terminaison d’API de test à partir de Microsoft Graph. Nous devons modifier le fichier de configuration généré pour qu’il appelle l’API de gestion du cycle de vie PAT à la place.

Conseil

Nous utilisons la collection et l’organisation de façon interchangeable dans ces documents. Si une variable de configuration a besoin d’un nom de collection, remplacez-la par le nom de votre organisation.

Pour ce faire, nous devons effectuer quelques opérations :

Mettre à jour la variable de configuration ENDPOINT pour https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview les API de gestion du cycle de vie PAT
Mettez à jour la variable de configuration SCOPE sur « 499b84ac-1321-427f-aa17-267ca6975798/.default » pour faire référence à la ressource Azure DevOps et à toutes ses étendues.

L’exemple suivant vous montre comment nous avons effectué cette configuration pour l’application Python Flask de démarrage rapide que nous avons générée via le Portail Azure dans la section précédente.

Veillez à suivre les instructions pour sécuriser votre clé secrète client, qui est initialement insérée en texte brut dans le fichier de configuration de l’application. En guise de meilleure pratique, supprimez la variable de texte brut du fichier de configuration et utilisez une variable d’environnement ou Azure KeyVault pour sécuriser le secret de leur application.

Au lieu de cela, vous pouvez choisir d’utiliser un certificat au lieu d’un secret client. L’utilisation de certificats est l’option recommandée si l’application sera éventuellement utilisée en production. Les instructions d’utilisation d’un certificat se trouvent à l’étape finale de la configuration de l’application de démarrage rapide.

Attention

Ne laissez jamais une clé secrète client en texte brut dans le code d’application de production.

Exemple : Configurer une application de démarrage rapide Python Flask pour l’API de gestion du cycle de vie PAT

Une fois que vous avez téléchargé votre application de démarrage rapide, installé ses dépendances et testé qu’elle s’exécute dans votre environnement, ouvrez le app_config.py fichier dans votre éditeur de choix. Le fichier doit ressembler à l’extrait de code suivant ; pour plus de clarté, les commentaires faisant référence à la configuration de l’API Microsoft Graph par défaut ont été supprimés :

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

Mettez à jour l’ID client ou la clé secrète client sur votre application avec l’ID client et la clé secrète client de votre application. En production, veillez à sécuriser la clé secrète client à l’aide d’une variable d’environnement, d’Azure KeyVault ou d’un certificat.
```
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.
```

Remplacez la variable par ENDPOINT votre URL de collection Azure DevOps et votre point de terminaison d’API. Par exemple, pour une collection nommée « testCollection », la valeur serait :

# 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'

Pour une collection nommée « testCollection », ce point de terminaison serait :

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

Modifiez la SCOPE variable pour référencer la ressource d’API Azure DevOps ; la chaîne de caractères est l’ID de ressource de l’API Azure DevOps, et l’étendue « .default » fait référence à toutes les étendues de cet ID de ressource.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Si votre application est configurée pour un locataire spécifique (plutôt que pour la configuration multilocataire), utilisez la valeur alternative pour la AUTHORITY variable, en ajoutant le nom de locataire spécifique dans « 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"
```

Vérifiez que le fichier final app_config.py correspond à ce qui suit, avec votre CLIENT_ID, votre ID de locataire et l’URL de collection. Pour des raisons de sécurité, vérifiez que le CLIENT_SECRET a été déplacé vers une variable d’environnement, Azure KeyVault ou échangé avec un certificat pour votre application inscrite :

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

Réexécutez l’application pour tester que vous pouvez obtenir tous les jetons PAT pour l’utilisateur demandeur. Une fois que vous avez vérifié que vous disposez, n’hésitez pas à modifier le contenu et 'app.py' l’annuaire 'ms-identity-python-webapp-master\templates' pour prendre en charge l’envoi de demandes au reste des points de terminaison de l’API de gestion du cycle de vie PAT. Pour obtenir un exemple d’application de démarrage rapide Python Flask qui a été modifiée pour prendre en charge les demandes adressées à tous les points de terminaison d’API de gestion du cycle de vie PAT, consultez cet exemple de dépôt sur GitHub.

Actualiser automatiquement un jeton d’accès Microsoft Entra

Une fois l’application configurée correctement et que l’utilisateur a acquis un jeton d’accès, le jeton peut être utilisé pendant une heure maximum. Le code MSAL fourni dans les deux exemples ci-dessus actualise automatiquement le jeton une fois qu’il expire. L’actualisation du jeton empêche l’utilisateur de se connecter à nouveau et d’acquérir un nouveau code d’autorisation. Toutefois, les utilisateurs peuvent avoir besoin de se reconnecter après 90 jours après l’expiration de leur jeton d’actualisation.

Explorer l’API de gestion du cycle de vie PAT

Dans l’exemple d’application GitHub et les applications de démarrage rapide ci-dessus, l’application a été préconfigurée pour effectuer des demandes avec les jetons Microsoft Entra que vous avez acquis. Pour en savoir plus sur les points de terminaison, les paramètres qu’ils acceptent et les éléments retournés dans les réponses, consultez la documentation de référence de l’API.

FAQ

Q : Pourquoi dois-je m’authentifier avec un jeton Microsoft Entra ? Pourquoi un PAT n’est-il pas suffisant ?

R : Avec cette API de gestion du cycle de vie PAT, nous avons ouvert la possibilité de créer de nouveaux PAT et de révoquer des PAT existants. Dans les mauvaises mains, cette API peut être utilisée par des acteurs malveillants pour créer plusieurs points d’entrée dans les ressources ADO de votre organisation. En appliquant l’authentification Microsoft Entra, nous espérons que cette API puissante sera plus sécurisée contre cette utilisation non autorisée.

Q : Dois-je disposer d’un locataire Microsoft Entra avec un abonnement Azure actif pour utiliser cette API ?

R : Malheureusement, cette API est disponible uniquement pour les utilisateurs qui font partie d’un locataire Microsoft Entra avec un abonnement Azure actif.

Q : Puis-je obtenir un exemple de cet exemple d’application pour un autre type de langage/framework/application ?

R : Nous aimons que vous souhaitez utiliser l’API dans votre langue de choix ! Si vous avez une demande d’exemple, passez à notre communauté de développement pour voir si quelqu’un d’autre a un exemple à partager. Si vous avez un exemple d’application que vous souhaitez partager à l’ensemble de l’audience Azure DevOps, faites-nous savoir et nous pouvons examiner la circulation sur ces documents plus largement !

Q : Quelle est la différence entre cette API de jeton et l’API d’administration de jeton ?

R : Cette API de jeton et l’API d’administration de jeton, tandis que similaire, servent différents cas d’usage et audiences :

Cette API de jeton est principalement destinée aux utilisateurs qui souhaitent gérer les PAT qu’ils possèdent dans un pipeline automatisé. Cette API autorise. Il vous donne la possibilité de créer des jetons et de mettre à jour des jetons existants.
L’API d’administration de jeton est destinée aux administrateurs de l’organisation. Administration peuvent utiliser cette API pour récupérer et révoquer des autorisations OAuth, notamment des jetons d’accès personnels (PAT) et des jetons de session auto-décrivant, des utilisateurs de leur organisation.

Q : Comment puis-je régénérer/faire pivoter des PAT via l’API ? J’ai vu cette option dans l’interface utilisateur, mais je ne vois pas de méthode similaire dans l’API.

R : Grande question ! La fonctionnalité « Régénérer » disponible dans l’interface utilisateur effectue effectivement quelques actions, qui sont entièrement réplicables via l’API.

Pour faire pivoter votre PAT, vous devez :

Comprendre les métadonnées du PAT à l’aide d’un appel GET ,
Créez un pat avec les métadonnées de l’ancien PAT à l’aide d’un appel POST .
Révoquer l’ancien PAT à l’aide d’un appel DELETE

Q : Je vois une fenêtre contextuelle « Besoin d’approbation d’administrateur » lorsque j’essaie de continuer à utiliser cette application. Comment puis-je utiliser cette application sans approbation d’administrateur ?

R : Il semble que votre locataire ait défini des stratégies de sécurité qui nécessitent que votre application dispose d’autorisations d’accès aux ressources de l’organisation. À ce stade, la seule façon de procéder à l’utilisation de cette application dans ce locataire consiste à demander à un administrateur d’accorder l’autorisation à l’application avant de pouvoir l’utiliser.

Étapes suivantes

En savoir plus sur les points de terminaison de l’API de gestion du cycle de vie PAT