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

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 vos PAT, ce qui vous permet de créer de nouveaux PAT et de renouveler ou d’expirer des PAT existants.

Dans cet article, nous vous montrons 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

• Autorisations : 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.

• Authentification :
  • Pour utiliser l’API, authentifiez-vous avec un jeton Microsoft Entra via l’ID OAuth De Microsoft Entra. Pour plus d’informations, consultez la section d’authentification.
  • Disposer d’un locataire Microsoft Entra avec un abonnement Azure actif.

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 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, effectuez les tâches suivantes :

• Disposer d’un locataire Microsoft Entra avec un abonnement Azure actif
• Inscrire une application dans son locataire Microsoft Entra
• Ajouter des autorisations Azure DevOps à l’application

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, fournissez un jeton d’accès Microsoft Entra en tant que Bearer jeton dans l’en-tête Authorization de votre demande. Pour plus d’informations et une liste complète des demandes disponibles, consultez la référence de l’API PAT.

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

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 dans la documentation sur les 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.

Pour commencer, consultez l’un des exemples suivants :

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

Une fois que vous clonez 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 doivent 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 suivre l’exemple suivant avec une application de démarrage rapide Python Flask.

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

1. 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 l’ID Microsoft Entra ->Inscriptions d’applications dans le Portail Azure.

   

2. Sélectionnez votre application et accédez aux autorisations d’API.

   

3. Sélectionnez Ajouter une autorisation et sélectionnez Azure DevOps -> vérifier user_impersonation -> sélectionnez Ajouter des autorisations.

   

4. Sélectionnez Démarrage rapide.

5. Sélectionnez votre type d’application : pour Python Flask, sélectionnez application web.

6. Sélectionnez votre plateforme d’application. Pour ce tutoriel, sélectionnez Python.

7. Assurez-vous que vous remplissez 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 ».

   

8. Téléchargez l’application de démarrage rapide et extrayez les fichiers.

   

9. 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 l’utilisateur 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. Modifiez le fichier de configuration généré pour qu’il appelle l’API de gestion du cycle de vie PAT à la place.

Effectuez les tâches suivantes :

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

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

1. Une fois que vous avez téléchargé votre application de démarrage rapide, installez ses dépendances et testez 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
   

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

3. 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'
   

4. 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"]
   

5. Si votre application est configurée pour un locataire spécifique (plutôt que 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"
   

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

7. Réexécutez l’application pour tester que vous pouvez obtenir tous les jetons PAT pour l’utilisateur demandeur. Une fois vérifié, vous pouvez 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 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 Microsoft Entra

Une fois que l’application est 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 précédents 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 les API de gestion du cycle de vie pat

Dans l’exemple d’application GitHub précédent et les applications de démarrage rapide, l’application est préconfigurée pour effectuer des demandes avec les jetons Microsoft Entra que vous avez acquis. Pour plus d’informations, consultez la documentation de référence de l’API.

Forum Aux Questions (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, les acteurs malveillants peuvent utiliser cette API pour créer plusieurs points d’entrée dans les ressources Azure DevOps 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. Les administrateurs 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 les 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, procédez comme suit :

1. Comprendre les métadonnées du PAT à l’aide d’un appel GET ,
2. Créez un pat avec les métadonnées de l’ancien PAT à l’aide d’un appel POST .
3. 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 dispose de stratégies de sécurité, ce qui oblige votre application à accorder des 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.

Q : Pourquoi est-ce que je vois une erreur telle que « Les principaux de service ne sont pas autorisés à effectuer cette action » lorsque j’essaie d’appeler l’API de gestion du cycle de vie PAT à l’aide d’un principal de service ou d’une identité managée ?

R : Les principaux de service et les identités managées ne sont pas autorisés. É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.

Étapes suivantes