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

Azure DevOps Services

Lorsque vous travaillez avec un grand ensemble de jetons d’accès personnels (PATs) 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 de PAT, vous pouvez facilement gérer les PATs associés à vos organisations à l’aide de processus automatisés. Cet ensemble complet d’API vous permet de gérer le PATs dont vous êtes propriétaire, 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 qui effectue des appels avec l’API du cycle de vie de PAT. Si vous souhaitez simplement voir la liste complète des points de terminaison disponibles, consultez les informations de référence sur les API ici.

Prérequis

pour utiliser l’API, vous devez vous authentifier à l’aide d’un jeton de Azure AD. Pour plus d’informations sur la procédure à suivre, consultez la section authentificationsuivante.

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, vous devrez peut-être accorder des autorisations d’accès aux ressources de l’organisation. À ce stade, le seul moyen 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 à d’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. Azure AD jetons sont un mécanisme d’authentification plus sécurisé que l’utilisation de PATs. Étant donné cette ’ capacité d’API à créer et à révoquer des PATs, nous voulons nous assurer que de telles fonctionnalités puissantes sont fournies aux utilisateurs autorisés uniquement.

pour obtenir et actualiser Azure AD des jetons d’accès, vous devez :

Important

les solutions « au nom de l’application » (par exemple, le “ workflow d’informations d’identification du client ” ) et tout autre workflow d’authentification qui n’émet pas de Azure AD jeton d’accès ne sont pas valides pour une utilisation avec cette API. si l’authentification multifacteur est activée dans votre locataire Azure AD, vous devez absolument utiliser le « workflow de code d’autorisation ».

Attention

le fait de disposer d’un locataire Azure AD avec un abonnement Azure actif est une condition préalable à l’utilisation de cette API.

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

pour appeler l’API directement, vous devez fournir un jeton d’accès Azure AD en tant que Bearer jeton dans l' Authorization en-tête de votre demande. Pour voir 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 Azure AD à l’aide de la bibliothèque MSAL et appelle notre API de gestion du cycle de vie de PAT.

la bibliothèque d’authentification Microsoft (MSAL) comprend plusieurs flux d’authentification compatibles que vous pouvez utiliser dans votre application pour acquérir et actualiser Azure AD jetons. Vous trouverez une liste complète des flux MSAL dans ” la documentation des 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 dans la rubrique choix de la méthode d’authentification appropriée pour Azure DevOps.

Pour commencer, suivez l’un des deux exemples suivants :

Cloner notre application Web de ballon python

nous vous avons fourni un exemple d’application web de ballon Python pour cette API que vous pouvez télécharger sur GitHub et peuvent être configurés pour être utilisés avec votre client Azure AD et votre organisation de Azure DevOps. l’exemple d’application utilise le déroulement du code d’authentification MSAL pour obtenir un jeton d’accès Azure AD.

Important

nous vous recommandons de prendre en main l’exemple d’application web de la fiole Python 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 Lisez-moi référentiel s. le fichier lisez-moi explique comment inscrire une application dans votre locataire Azure AD, configurer l’exemple pour utiliser votre client Azure AD et exécuter votre application clonée.

Génération d’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 déroulement du code d’autorisation, mais 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 de 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 Azure AD développer docs. Nous allons étudier un exemple dans lequel nous avons effectué cette opération pour une application de démarrage rapide de la fiole Python.

Exemple : prise en main d’une application de démarrage rapide pour la fiole python

  1. 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 lesinscriptions d’applications dans le Portail Azure.

    Open

  2. Sélectionnez votre application, puis accédez à autorisations API.

    Select your application and navigate to

  3. sélectionnez ajouter une autorisation et sélectionnez Azure DevOps - cochez user_impersonation - sélectionnez ajouter des autorisations.

    Add the

  4. Sélectionnez démarrage rapide dans le panneau de navigation de gauche.

  5. Sélectionnez votre type d’application : pour la fiole Python, sélectionnez application Web.

  6. Sélectionnez la plateforme de votre application. Pour ce didacticiel, sélectionnez « Python ».

  7. Assurez-vous que vous avez respecté les conditions préalables requises, puis autorisez Portail Azure à apporter les modifications nécessaires pour configurer votre application. L' URL de réponse est l’URL de redirection qui a été définie lors de la création de l’application + /getAToken ” .

    Allow the Azure portal to make the necessary changes to configure your application

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

    Download the Quickstart application and extract the files

  9. Installez les spécifications 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 modifier ce point de terminaison pour 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.

    Install the application requirements and run the application to ensure you have all necessary dependencies

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 devrons modifier le fichier de configuration généré pour qu’il appelle plutôt l’API de gestion du cycle de vie de PAT.

Conseil

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

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

  1. Mettre à jour la variable de configuration du point de terminaison vers pour les API de gestion du cycle de vie Pat
  2. mettez à jour la variable de configuration d' étendue en « 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 de la fiole python de démarrage rapide que nous avons générée par le Portail Azure dans la section précédente.

Veillez à suivre les instructions pour sécuriser votre clé secrète client, qui est insérée initialement en texte brut dans le fichier de configuration de l’application. Il est recommandé de supprimer la variable de texte brut du fichier de configuration et d’utiliser une variable d’environnement ou Azure Key Vault pour sécuriser le secret de l’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 finira par être 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 de l’application de production.

Exemple : configurer une application de démarrage rapide pour la fiole Python pour l’API de gestion du cycle de vie de PAT

  1. Une fois que vous avez téléchargé votre application de démarrage rapide, installé ses dépendances et testé son exécution dans votre environnement, ouvrez le app_config.py fichier dans votre éditeur de votre choix. Le fichier doit ressembler à l’extrait de code suivant : pour plus de clarté, les commentaires référençant la configuration de l’API de 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 pour votre application avec l' ’ ID client et la clé secrète client de l’inscription de l’application. Lorsque vous êtes en production, veillez à sécuriser la clé secrète client à l’aide d’une variable d’environnement, d’Azure Key Vault ou en basculant vers 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 ENDPOINT variable par votre URL de collection Azure DevOps et votre point de terminaison d’API. Par exemple, pour une collection nommée « testCollection », la valeur est :

    # 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 est le suivant :

    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 api Azure DevOps ; la chaîne de caractères est l’ID de ressource de l’api Azure DevOps et la “ portée. 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 multi-locataire), utilisez l’autre valeur 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 app_config.py fichier final correspond à ce qui suit, avec votre CLIENT_ID, l’ID de locataire et l’URL de collection. Pour des raisons de sécurité, assurez-vous que le CLIENT_SECRET a été déplacé vers une variable d’environnement, Azure Key Vault ou remplacé par 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 vérifier que vous pouvez obtenir tous les jetons PAT pour l’utilisateur à l’origine de la demande. Une fois que vous avez vérifié que vous avez, n’hésitez pas à modifier le contenu de 'app.py' et de l' 'ms-identity-python-webapp-master\templates' annuaire pour qu’il prenne en charge l’envoi de demandes au reste des points de terminaison de l’API de gestion du cycle de vie de Pat. Pour obtenir un exemple d’application de démarrage rapide de la fiole Python qui a été modifiée pour prendre en charge les demandes à tous les points de terminaison de l’API de gestion du cycle de vie de PAT, consultez cet exemple référentiel sur GitHub.

actualiser automatiquement un jeton d’accès Azure AD

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. 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’obtenir un nouveau code d’autorisation. Toutefois, les utilisateurs devront peut-être se reconnecter après 90 jours après l’expiration de leur jeton d’actualisation.

Explorez les API de gestion du cycle de vie de PAT ’

dans l’exemple d’application et les applications de démarrage rapide ci-dessus GitHub, l’application a été préconfigurée pour effectuer des demandes 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 les informations renvoyées dans les réponses, consultez la documentation de référencesur les API.

Questions fréquentes (FAQ)

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

R : Avec cette API de gestion du cycle de vie de PAT, nous avons ouvert la possibilité de créer de nouvelles PATs et de révoquer les PATs existants. Dans les mauvaises mains, cette API pourrait ê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 est plus sécurisée par rapport à cette utilisation non autorisée.

Q : ai-je besoin d’un locataire Azure AD avec un abonnement Azure actif pour utiliser cette API ?

R : malheureusement, cette API est uniquement disponible 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/d’infrastructure/d’application ?

R : Nous aimerions que vous souhaitiez utiliser l’API dans le langage de votre choix. si vous avez une demande pour obtenir un exemple, accédez à notre Community Dev pour voir si quelqu’un d’autre a un exemple à partager. si vous avez un exemple d’application que vous ’ aimez partager avec un public plus grand Azure DevOps, ’ le nous savoir et nous pouvons nous pencher sur la façon de le diffuser 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, bien que similaire, répondent à différents cas d’usage et audiences :

  • Cette API de jeton est principalement destinée aux utilisateurs qui souhaitent gérer les PATs qu’ils possèdent dans un pipeline automatisé. Cette API autorise. Elle 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 les autorisations OAuth, y compris les jetons d’accès personnels (PATs) et les jetons de session auto-descriptifs, des utilisateurs de leur organisation.

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

R : Bonne question ! La “” fonctionnalité de régénération disponible dans l’interface utilisateur effectue en fait quelques actions, qui sont entièrement réplicables par le biais de l’API.

Pour faire pivoter votre PAT, vous devez :

  1. Comprendre les métadonnées du PAT à l’aide d’un appel de mise en route ,
  2. Créer une nouvelle PAT avec les anciennes ’ métadonnées de Pat à l’aide d’un appel de ’ ,
  3. Révoquer l’ancien PAT à l’aide d’un appel Delete

Q : une fenêtre contextuelle « nécessite une approbation d’administrateur » s’affiche lorsque j’essaie de poursuivre l’utilisation de cette application. Comment puis-je utiliser cette application sans approbation de l’administrateur ?

R : Il semble que votre locataire ait défini des stratégies de sécurité qui nécessitent que votre application dispose des autorisations nécessaires pour accéder aux ressources de l’organisation. À ce stade, le seul moyen 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