Blog

Créez des applications sophistiquées pour votre environnement PagerDuty à l'aide d'OAuth 2.0 et des étendues d'API

par Murs de Mandi 26 octobre 2023 | 9 minutes de lecture

De nombreux clients PagerDuty créent leurs propres applications pour les aider à gérer leurs environnements PagerDuty . Les équipes peuvent avoir un certain nombre de flux de travail qui pourraient bénéficier d'une application personnalisée. Un administrateur PagerDuty souhaitera peut-être pouvoir charger des fichiers CSV avec de nouveaux utilisateurs et leurs informations de contact dans PagerDuty lorsque de nouvelles équipes rejoignent la plate-forme, ou charger de nouveaux services avant leur mise en production. La création d'applications personnalisées pour PagerDuty peut faciliter ces tâches administratives lorsqu'un autre composant est le système d'enregistrement de ces données.

En mai, nous avons examiné mise à jour des outils personnalisés pour les portées d'API vs l'original de PagerDuty Clés API , et a utilisé l'application elle-même pour demander les jetons (via certains scripts), mais les développeurs peuvent également permettre aux utilisateurs de se connecter à une application et de s'authentifier auprès de PagerDuty lui-même pour contrôler quels objets seront disponibles.

Les utilisateurs connectés n'auront accès qu'aux objets qu'ils pourraient également voir via l'interface utilisateur Web, et leur accès sera également limité par les portées de l'application que vous créez. La combinaison des autorisations et des portées offre un contrôle complet sur les utilisateurs qui peuvent voir et modifier quels objets, que ce soit via l'interface utilisateur Web, l'API ou les applications personnalisées.

Nous utiliserons un exemple d'application que notre équipe d'ingénieurs a publié à titre d'exemple.

Une partie du flux de travail se déroulera dans l'interface utilisateur de PagerDuty et une partie se déroulera sur votre poste de travail. Pour suivre toutes les étapes, vous devez être administrateur de votre compte PagerDuty et pouvoir exécuter des applications Python sur votre poste de travail.

Nous allons créer une application en tant qu'administrateur PagerDuty , et une partie du flux de travail de l'application elle-même consistera à demander à l'utilisateur de se connecter à PagerDuty. L'application sera alors uniquement autorisée à accéder aux objets auxquels l'utilisateur connecté peut accéder et qui ont été inclus dans les étendues de l'application.

Enregistrer une demande

Ce flux de travail sera similaire à ce que nous avons vu dans le billet de blog précédent, mais il existe une nouvelle fonctionnalité qui facilitera les choses !

Notre exemple d'application devra être enregistré auprès de PagerDuty afin de donner accès aux objets PagerDuty . Pour une description détaillée du processus d'enregistrement de l'application, consultez le documentation du développeur .

Seuls les administrateurs de compte peuvent créer des applications à l'aide des fonctionnalités Scoped OAuth 2.0. (Les utilisateurs réguliers peuvent toujours créer leurs propres applications, mais les fonctionnalités sont limitées à Utilisateur classique OAuth .)

Dans votre compte PagerDuty , ouvrez le Intégrations menu en haut de l'écran et cliquez sur Inscription à l'application dans le Outils de développement colonne. Ajoutez une nouvelle application en utilisant le bouton à droite, ou vous pouvez mettre à jour une application existante.

Donnez un nom à votre application, une description et sélectionnez « OAuth 2.0 », puis cliquez sur « Suivant » :

The PagerDuty web UI. In this dialog page, a form is presented to the user for “Add New App”. The form has two headlines, “Info & Functionality”, which is active, and “Configure OAuth 2.0” which is inactive. The form contains two sections. In the “App Information” section, the user is required to fill out a Name field and a Description field. In this example, the Name of the app is “My Access App for Services”, with the Description “Allow users access to services”. In the “Functionality” section, the user is asked if the app will need OAuth 2.0 or Events Integration with checkboxes. The “OAuth 2.0” box is checked. At the bottom of the form, a link for “Cancel” and a button marked “Next” are available.

Sur la page suivante, « Scoped OAuth » est sélectionné par défaut ; laissez-le sélectionné. Dans la section suivante, nous souhaitons ajouter une « URL de redirection » pour notre exemple d'application. Dans le flux OAuth, le rappel est l'emplacement de l'application que vos utilisateurs utiliseront pour accéder aux objets PagerDuty et peut être hébergé partout où les utilisateurs peuvent y accéder. Il n'est pas nécessaire qu'il soit accessible au public ou accessible à PagerDuty.

Notre exemple d'application est conçu pour s'exécuter localement sur votre poste de travail par défaut, en utilisant hôte local . Configurez votre URL de redirection pour http://localhost:5000/callback . Notez qu'il n'y a pas https ! Ceci est juste un exemple d'application et n'est pas destiné à la production.

Ensuite, sélectionnez les objets et le type d'accès que vous souhaitez essayer pour votre application. Je vais commencer par Prestations de service mais fais-le Accès en lecture seulement:

A section of the PagerDuty web UI page for app configuration. This section is a three-column list of potential objects in PagerDuty that an app might require access to. The first column is made up of names of objects, such as “Response Plays”, “Schedules”, and “Services”. The second column presents checkboxes to the user to allow “Read Access” to the objects, and the third column presents checkboxes to allow “Write Access”. All boxes are unchecked except the “Read Access” box for “Services”.

Pour que notre exemple d'application fonctionne, vous devrez également ajouter un accès en lecture pour l'objet Utilisateurs !! Les applications que vous créez n'ont peut-être pas besoin de cet accès ! Vous pouvez configurer l'accès de manière à ce qu'il soit aussi large ou restreint que nécessaire pour les tâches que vous devez effectuer. Si vous n'êtes pas sûr des étendues qui s'appliquent à quels objets, reportez-vous à la section Documentation de l'API .

Lorsque vous avez choisi vos portées, cliquez sur le Inscription à l'application bouton en bas de l'écran.

Nouvelle fonctionnalité :Vous pouvez maintenant télécharger un json dossier avec vos identifiants ! Vous n'aurez toujours qu'une seule occasion de le faire. Vous recevrez un json fichier avec votre identité du client et client_secret dedans. Nous en aurons besoin pour configurer notre exemple d'application, alors cliquez sur Télécharger JSON et puis Continuer .

A dialog box in the PagerDuty web UI. The title of the box is “OAuth 2.0 Client Information”. There are two read-only text boxes. The first box is “Client ID”. The content in the box is blurred out. There is a copy tool at the right of the box. The second box, below the first, is “Client Secret” and the content here is represented by dots. There is also a copy tool on this box. Below the text boxes are two buttons: “Download JSON” in gray and “Continue” in blue.

Utilisation d'un exemple d'application pour récupérer un nouveau jeton utilisateur

Une fois votre application enregistrée et que vous avez reçu le fichier json d'autorisation, vous pouvez utiliser le identité du client et client_secret pour demander un jeton. Il s'agit d'un processus en deux étapes : récupérer un code d'autorisation et utiliser ce code pour générer un jeton. Les codes d'autorisation ne sont valides que pendant 30 secondes. Vous souhaiterez donc probablement placer les deux demandes dans le même outil ou script, même si vous n'écrivez pas une application complète.

Vous pouvez également utiliser l'un de nos échantillons, par exemple Python ou Javascript / Node.js .

Je vais utiliser l'exemple Python avec quelques ajustements. Il s'agit d'une application Flask assez simple qui utilisera les éléments d'autorisation que nous avons reçus du processus de création de l'application PagerDuty , présentera à l'utilisateur un écran d'autorisation de connexion, fera les demandes pour moi et me donnera le jeton que je peux utiliser pour mes propres demandes dans les scripts. ou avec curl, similaire aux exemples de notre publication précédente .

Téléchargez, configurez et exécutez l'exemple d'application

Suivez les instructions de l'exemple d'application README.md fichier pour configurer votre application. Vous utiliserez le contenu du fichier json que vous avez téléchargé à partir de l'interface utilisateur Web - le identité du client et client_secret - dans le config.json déposer:

{

« PD_CLIENT_ID » : « xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx »,

« PD_CLIENT_SECRET » : « xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx »,

« REDIRECT_URI » : « http://localhost:5000/callback »

}

Une fois votre config.json Une fois le fichier créé, effectuez le reste des étapes pour installer les dépendances de l'application. Selon votre environnement et les versions de Python que vous avez installées, vous devrez peut-être utiliser le python3 commande:

  • Créer un environnement virtuel pour Python : python -m venv env
  • Activer l'environnement : source env/bin/activate
  • Installer les dépendances : pip install -r exigences.txt
  • Exécutez l'application : application python.py

Si vous recevez un message d'erreur indiquant que le port est utilisé, vous pouvez effectuer une mise à jour vers un autre port dans le application.py fichier, sur la dernière ligne.

NB: Si vous devez déplacer le port sur lequel votre app.py s'exécute, vous devrez revenir aux étapes de configuration dans l'interface utilisateur et modifier votre URI de redirection. Assurez-vous d'enregistrer toutes vos modifications !

Connectez-vous et récupérez votre token

Quand application.py est en cours d'exécution, vous pourrez ouvrir l'url dans votre navigateur et vous connecter à PagerDuty:

Screen capture of a web browser. The location bar is set to localhost:5050. The page title is “PagerDuty OAuth2 Sample” in black text on white background and there is a link “Connect to PagerDuty”.

Lorsque vous cliquez sur le lien « Se connecter à PagerDuty», vous serez redirigé vers une page de connexion hébergée sur identité.pagerduty.com :

A screenshot of the login page for identity.pagerduty.com. The first line is PagerDuty in large letters. A white dialog box asks the user to “Sign in to your account to authorize My Access App for Services”. A clear textbox is labeled “Email” and there is a blue button underneath titled “Next”. At the bottom of the dialog is an additional message, “Don’t have a PagerDuty account? Sign up”. “Sign up” is a link to another page.

Ce flux de travail assure la sécurité de votre compte. Votre équipe se connecte directement à PagerDuty et les jetons sont utilisés pour transmettre l'autorisation. Votre application n'a pas besoin de gérer l'authentification ou l'autorisation ! Laissez PagerDuty s'en occuper.

Connectez-vous avec votre identifiant et votre mot de passe. PagerDuty vous demandera d'autoriser l'application sur votre compte :

A screen capture of the authorization. Three icons appear at the top: A lock, a green checkmark, and a box” to represent the workflow. The title of the dialog is “My Access App for Services” and the rest of the text reads: “wants to access your account: PULO4NW. The following permissions are requested by the above app. Please review these and consent if it is OK. User ID - Your user account ID. services.read - Read access to PagerDuty Services. users.read - Read access to PagerDuty Users”. Below the list of data items is a white button with black text: “Submit Consent”. Below that is a gray box with black text: “Cancel”. At the bottom is smaller text: “Your consent to provide access is required. If you do not approve, click Cancel, in which case no information will be shared with the app.”

Cliquez sur « Soumettre le consentement ». Vous serez renvoyé vers votre redirection_uri , dans ce cas, le application.py sur hôte local .

Votre jeton fera partie des informations renvoyées à l'application et fait partie de la corps des données de retour. Vous pouvez modifier un peu le code pour l'imprimer sur la page. J'ai ajouté jeton et jeton d'actualisation à ma sortie à titre d'exemple :

A screen capture of a web browser. Part of the location is shown as localhost:5050/callback?iss=... The page title is “PagerDuty OAuth2 Sample” in black text on white background. A generic user avatar is shown, a white outline of the stylized head and shoulders of a person on a gray background. There are three lines of text. The first is “Hello, Bethany Developer!” The second is the user’s token. The text of the token starts “pdus+0X” and the remaining text is blurred out. The third line is the user’s refresh token. This token also starts “pdus+1X” and the remaining text is blurred out.

Ce jeton est désormais à vous et peut être utilisé dans des scripts et des outils, dans le langage de votre choix. Incorporez-le dans vos requêtes API en tant qu'en-tête « Authorization » :

Autorisation : Porteur pdus+_xxxxxxxxxxxxxxxxxxxxxxxxxxx

Par exemple, voici un script shell pour demander /prestations de service :

JETON = $PD_API_KEY

POINT FINAL = « services »

curl -X GET –header 'Type de contenu : application/json' \

–url https://api.pagerduty.com/$ENDPOINT \

–header 'Accepter : application/vnd.pagerduty+json ;version = 2' \

–header « Autorisation : Porteur $TOKEN »

Portées non autorisées

Étant donné que notre jeton a une portée très étroite, vous verrez une erreur si vous essayez de l'utiliser pour accéder à autre chose que prestations de service et utilisateurs . Si j'essayais d'utiliser ce jeton pour accéder au /incidents point de terminaison, je recevrais l'erreur suivante :

{« erreur » : {« message » : « jeton manquant les portées requises » », « required_scopes » : « incidents.read » », « token_scopes » : « openid services.read users.read »}}

Délais d'attente et actualisation

Contrairement à nos clés API, les jetons OAuth ont une durée de vie limitée. Le jeton au porteur que nous avons reçu dans la dernière section ne sera valable que 24 heures. L'exemple de code d'application n'a pas d'option pour actualiser les jetons, il est donc plus simple de demander un nouveau jeton ; revenez simplement à la première URL et cliquez à nouveau sur le lien « Se connecter à PagerDuty» pour obtenir un nouveau jeton.

Lorsque vous incorporez ce flux dans une autre application, vous souhaiterez utiliser le jeton d'actualisation afin que les utilisateurs n'aient pas à se connecter à plusieurs reprises. Ils peuvent autoriser leur compte et votre application peut gérer les jetons sur le backend et actualiser selon les besoins. Pour plus d'informations sur l'utilisation des jetons d'actualisation, consultez le documents .

Révoquer les jetons et supprimer les applications

Si vous devez révoquer les jetons d'une application, vous pouvez le faire sur le Client panneau de la page de configuration. Vous pouvez révoquer tous les jetons actifs de l'application, et vous pouvez supprimer le client lui-même et générer un nouveau secret.

A page in the PagerDuty web UI for “Edit App > OAuth 2.0”. The title of the section is “Configure OAuth 2.0”. The second line of text reads “Create apps that administer or get data from PagerDuty via REST API. Learn More”. “Learn More” is a link to another page. There are two tabs in the next section: “Scopes” and “Client”. The “Client” tab is active. Text is highlighted in a light-blue box: “If you’ve lost the client secret, you will have to delete client OAuth below and configure it again.” There is a text box labeled “Client ID”. The contents of the text box are blurred out. There is a copy tool at the right of the box. The next section is labeled “Revoke All Tokens”, with the option “Revoke all client tokens from this application.” and a red button labeled “Revoke”. The last section is labeled “Delete Client”, with the option “Delete Client OAuth from this application.” and a red button labeled “Delete”.

Lorsque vous supprimez le client OAuth de votre application, vous devrez mettre à jour tout votre code susceptible d'utiliser cette configuration d'application pour communiquer avec PagerDuty.

Après avoir cliqué Supprimer , vous serez renvoyé à l'écran principal Modifier l'application écran. Pour créer un nouveau client OAuth pour votre application, ajoutez à nouveau OAuth 2.0 à votre demande de la même manière que ci-dessus.

Si votre équipe n'a plus besoin d'une application, vous pouvez désormais supprimer l'intégralité de l'application de votre Inscription à l'application page:

A portion of the PagerDuty web UI, a table with six columns and four rows. The columns represent: an icon for the included app; the name and description of the app; what authentication the app requires; the PagerDuty object ID of the app; whether the app is “Private” or “Public”; and a clickable ellipsis with options. The ellipsis for the second row is shown clicked and a small dialog box is displayed with two options: “Edit”, in black text, with a pencil icon, and “Delete”, in red text, with a trash can icon.

Cliquez simplement sur le menu à trois points sur le côté droit de la liste de votre application et sélectionnez Supprimer .

La suppression de l'application supprime tous les secrets et révoque tout jetons .

Dites-nous ce que vous en pensez!

Avez-vous commencé à utiliser Scoped OAuth dans vos outils ? Faites-le nous savoir ! Rejoignez notre Forums communautaires ou contactez-nous équipe-communautaire@pagerduty.com Nous aimerions savoir ce que vous pensez des nouvelles fonctionnalités et ce que vous espérez voir à l’avenir.

Facebook LinkedIn Twitter

Vous aimerez peut-être aussi ceux-ci...