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

Article
11/17/2022

Azure DevOps Services

Lorsque vous utilisez un grand ensemble de jetons d’accès personnels (PAT), 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 Azure Active Directory (Azure AD) et effectue des appels avec l’API de cycle de vie PAT. Si vous souhaitez simplement afficher la liste complète des points de terminaison disponibles, consultez la référence de l’API ici.

Prérequis

Pour utiliser l’API, vous devez vous authentifier avec un jeton Azure AD. 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 Azure AD 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. Pour l’instant, 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 Azure Active Directory (Azure AD)

Contrairement aux autres API Azure DevOps Services, les utilisateurs doivent fournir un jeton d’accès Azure AD pour utiliser cette API au lieu d’un jeton PAT. Les jetons Azure AD 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 ces fonctionnalités puissantes sont accordées aux utilisateurs autorisés uniquement.

Pour acquérir et actualiser des jetons d’accès Azure AD, vous devez :

Important

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

Attention

Avoir un locataire Azure AD 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 Azure AD, 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 Azure AD en tant que Bearer jeton dans l’en-tête Authorization de votre demande. Pour afficher les exemples et obtenir la 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 Azure AD à 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 Azure AD. 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 le 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 Azure AD 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 Azure AD.

Important

Nous vous recommandons de bien démarrer avec 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. Lisez-moi explique comment inscrire une application dans votre locataire Azure AD, configurer l’exemple pour utiliser votre locataire Azure AD et exécuter votre application clonées.

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 démarrage rapide suit le flux de code d’autorisation, mais le fait avec un point de terminaison Microsoft API Graph. Les utilisateurs devront mettre à jour la configuration de l’application pour pointer 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 du développement Azure AD. Nous allons vous guider dans un exemple où nous l’avons fait pour une application de démarrage rapide Python Flask.

Exemple : Démarrage avec une application de démarrage rapide Python Flask

Une fois que vous avez inscrit votre application dans un locataire Azure AD disposant d’un abonnement Azure actif, accédez à votre application inscrite sous Azure Active Directory ->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 -> vérifier user_impersonation -> sélectionner Ajouter des autorisations.
Sélectionnez Démarrage rapide dans le volet de navigation gauche.
Sélectionnez le 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 microsoft API 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 manière 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 https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview de configuration ENDPOINT pour les API de gestion du cycle de vie PAT
Mettez à jour la variable de configuration SCOPEsur « 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 de 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 bonne pratique, supprimez la variable en 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’une clé secrète client. L’utilisation de certificats est l’option recommandée si l’application sera finalement 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 par défaut de Microsoft API Graph 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 vers 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 votre ENDPOINT 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 le 'ms-identity-python-webapp-master\templates' répertoire pour prendre en charge l’envoi de 'app.py' 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 de l’API de gestion du cycle de vie PAT, consultez cet exemple de dépôt sur GitHub.

Actualiser automatiquement un jeton d’accès Azure AD

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 reconnecter 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 ci-dessus et les applications de démarrage rapide, l’application a été préconfigurée pour effectuer des requêtes avec les jetons Azure AD que vous avez acquis. Pour en savoir plus sur les points de terminaison, les paramètres qu’ils acceptent et ce qui est retourné dans les réponses, consultez la documentation de référence de l’API.

Forum aux questions

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

Un: 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 Azure AD, 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 Azure AD avec un abonnement Azure actif pour utiliser cette API ?

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

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

Un: 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 disposez d’un exemple d’application que vous souhaitez partager avec le plus grand public Azure DevOps, faites-nous savoir et nous pouvons l’examiner plus largement sur ces documents.

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

Un: Cette API de jeton et l’API d’administration de jeton, tout en étant similaires, 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 de nouveaux jetons et de mettre à jour des jetons existants.
L’API d’administration de jeton est destinée aux administrateurs de l’organisation. Les administrateurs peuvent utiliser cette API pour récupérer et révoquer des autorisations OAuth, y compris des jetons d’accès personnels (PAT) et des jetons de session autodéclarants, 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.

Un: Grande question ! La fonctionnalité « Régénérer » disponible dans l’interface utilisateur effectue en fait 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 ?

Un: 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. Pour l’instant, 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