L'API REST PagerDuty fournit plus de 200 points de terminaison permettant aux utilisateurs d'accéder par programmation aux objets et aux flux de travail de la plateforme PagerDuty . Les équipes exploitent ces API pour rationaliser la création et la gestion des utilisateurs, des équipes, des services et d'autres composants de leur environnement.

Jusqu'à présent, l'accès à l'API REST était autorisé et authentifié via Clés API . Ces clés sont gérées dans l'interface utilisateur Web et fournissent un accès tout ou rien aux objets du compte, ce qui les rend trop permissives pour de nombreuses équipes. PagerDuty Engineering a donc travaillé à la création d'un ensemble complet de portées d'API à utiliser avec les jetons OAuth2.0.

Chaque objet de l'API REST PagerDuty aura au moins une portée, lire , et de nombreux objets auront également écrire Vous pourrez paramétrer vos applications pour n'avoir que l'accès dont elles ont besoin pour fonctionner correctement, sans vous soucier qu'elles auront également accès à tout le reste de votre compte.

Pour les personnes qui utilisent actuellement des clés API, elles continueront de fonctionner pour le moment (restez à l'écoute d'une éventuelle fin de vie à l'avenir), mais la migration vers OAuth avec portée aidera les équipes à gérer l’accès et à adhérer aux principes du moindre privilège.

Pour une introduction vidéo aux portées d'API, consultez cette vidéo sur notre Chaîne Youtube .

Configurer une application

Le premier changement que vous remarquerez lors de la configuration de l'accès API avec des portées est que l'accès est géré via un application . Celles-ci ne seront pas gérées via la section « Clés d'accès API » sous le menu « Intégrations » ; vous devrez plutôt vous rendre dans « Enregistrement d'application » (anciennement appelé « Mode développeur ») et procéder au processus de configuration de l'application. La configuration de ces éléments est limitée aux administrateurs et aux propriétaires de votre compte.

Une fois l'application créée, vous aurez la possibilité d'y ajouter Scoped OAuth :

Pour les applications qui prennent en charge Scoped OAuth, la boîte de dialogue suivante vous permet de sélectionner les objets qui doivent être disponibles pour les jetons dérivés de cet accès à l'application. Vous pourrez sélectionner autant d'objets que nécessaire pour votre cas d'utilisation :

Après avoir cliqué Sauvegarder , une fenêtre contextuelle contenant deux informations importantes s'affichera : identité du client et Secret du client qui sera utilisé pour fournir des jetons pour l'accès à cette application.

Vous en aurez besoin pour provisionner des jetons, alors stockez-les dans un coffre-fort ou un autre emplacement ou application que vous utilisez pour les certificats, les mots de passe ou les secrets.

Trouver des portées

Comme vous pouvez le voir dans la capture d'écran ci-dessus, il existe de nombreuses portées potentielles dont vos jetons pourraient avoir besoin, en fonction des objets auxquels vous accéderez via l'API.

Heureusement, le Documentation de l'API a été mis à jour pour inclure les portées nécessaires pour tous les points de terminaison d'objet. Chaque type de demande aura une note qui comprend la portée et si la demande nécessitera un accès en lecture ou en écriture. Cependant, de manière générale, les demandes utilisant des méthodes GET (utilisées pour répertorier ou obtenir des informations) ne nécessiteront qu'un accès en lecture, tandis que les demandes PUT, POST et DELETE nécessiteront un accès en écriture.

Demande de jetons

Les jetons, associés au client de portée dans votre application, seront demandés à https://identity.pagerduty.com/oauth/token en utilisant les informations d'identification que vous avez reçues lors de la création de l'application. Vous trouverez le format de la demande dans la documentation de l'API ici . Les autres données requises sont votre région (États-Unis ou UE) et votre sous-domaine (votrecompte.pagerduty.com). Chaque jeton que vous demandez doit spécifier les domaines pour lesquels il sera valide.

 curl -i --request POST \ 

 https://identity.pagerduty.com/oauth/token \ 

 --header 'Type de contenu : application/x-www-form-urlencoded' \ 

 --data-urlencode 'grant_type=informations_d'identification_du_client' \ 

 --data-urlencode 'client_id={CLIENT_ID}' \ 

 --data-urlencode 'client_secret={CLIENT_SECRET}' \ 

 --data-urlencode 'scope=as_account-us.companysubdomain incidents.read services.read' 

Les étendues incluses dans un jeton peuvent être l'ensemble des étendues incluses dans l'application, ou un sous-ensemble de ces étendues, selon la manière dont votre organisation préfère gérer les jetons. Les jetons sont renvoyés dans un document JSON :

 { 

 'access_token': 'pdus+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 

 'scope': 'as_account-us.companysubdomain incidents.read services.read', 

 'token_type': 'porteur', 

 'expire_in': 2592000 

 } 

Ces jetons ont une date d'expiration ! C'est un grand changement par rapport aux clés API qui n'expirent jamais. Les jetons devront être renouvelés toutes les 24 heures.

De plus, pour aider les utilisateurs disposant d'analyseurs de référentiels à s'assurer que les jetons ne sont pas enregistrés, chaque jeton PagerDuty commencera par « pd<region> +”, donc soit pdus+ ou pdeu+ afin que les jetons soient facilement identifiables.

Une fois qu'un jeton est créé, c'est à vous de décider comment le distribuer et le gérer. Les jetons ne sont pas répertoriés dans l'interface utilisateur Web ni disponibles sur la plateforme. Depuis la page de l'application, vous aurez la possibilité de révoquer tous les jetons associés à l'application, mais pas les jetons individuels.

Utilisation des jetons

Si vous avez accédé à l'API via des scripts personnalisés, vous devrez effectuer quelques mises à jour pour utiliser les nouveaux jetons.

Pour les scripts shell qui utilisent des outils de ligne de commande comme boucle ou wget pour effectuer leurs requêtes https, vous devrez mettre à jour le Autorisation entête:

 --header 'Autorisation : Porteur $TOKEN' 

De même, dans des outils comme Postman, vous souhaiterez définir l'autorisation sur un jeton de porteur. Pour en savoir plus sur la façon de procéder dans Postman, consultez la Documentation du facteur .

Si vous utilisez l'une des différentes bibliothèques clientes pour l'API de PagerDuty, consultez la documentation de ces projets pour déterminer si une modification du code est requise. Par exemple, dans pdpyras , un constructeur de session est disponible spécifiquement pour les jetons OAuth2.0 :

 # API REST v2 avec un jeton d'accès OAuth2 : 

 session_oauth = pdpyras.APISession(OAUTH_TOKEN, auth_type='oauth2') 

Selon les langages de programmation que vous utilisez, des solutions plus sophistiquées ou une prise en charge des jetons OAuth2.0 peuvent être disponibles. Un exemple de code pour plusieurs langages est également inclus dans le Documentation sur le site du développeur.

Gestion des jetons et des applications

La conception de votre application et la granularité de vos jetons dépendent de vous et des exigences de sécurité de votre organisation. Voici quelques méthodes suggérées pour vous aider à démarrer.

Qui fournit les jetons

Étant donné que les jetons OAuth Scoped auront une expiration de 30 jours, les organisations avec de nombreuses équipes accédant par programmation à l'API PagerDuty trouveront probablement plus facile de partager les identité du client et Secret du client avec des équipes individuelles et leur permettre de provisionner leurs propres jetons. Les administrateurs peuvent choisir de créer des applications pour chaque équipe ou type d'application afin de contrôler qui aura accès à l'API et à quels objets.

Les équipes plus petites, ou celles qui ont besoin de plus de contrôle sur l'accès aux ressources, peuvent souhaiter conserver le identité du client et Secret du client aux administrateurs de compte, qui créeront et partageront ensuite des jetons avec les équipes via un stockage sécurisé.

Applications à portée complète, jetons à portée limitée

Pour les cas d'utilisation qui nécessiteront l'accès à de nombreux objets différents, vous pouvez provisionner l'application pour inclure toutes les portées. Étant donné que les jetons peuvent être demandés avec un sous-ensemble de toutes les portées autorisées, les jetons individuels peuvent être limités à ce que l'application cliente utilisera dans l'API.

Cette méthode permet de réduire le nombre d'applications à gérer dans le compte PagerDuty . Les administrateurs peuvent provisionner des applications pour des équipes ou des services et fournir des jetons avec des portées plus limitées.

Essayez-le et faites-le nous savoir

Scoped OAuth est désormais disponible en tant que fonctionnalité d'accès anticipé et sera disponible de manière générale sur tous les comptes à la fin du mois de mai 2023. Essayez-le et dites-nous ce que vous en pensez ! Inscrivez-vous pour un accès anticipé sur https://www.pagerduty.com/early-access/ ou contactez votre équipe de compte pour en savoir plus. Vous pouvez également rejoindre notre Forum de la communauté si tu as des questions.