Blog

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

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

De nombreux clients PagerDuty créent leurs propres applications pour gérer leurs environnements. Les équipes peuvent avoir de nombreux workflows qui pourraient bénéficier d'une application personnalisée. Un administrateur PagerDuty peut souhaiter charger des fichiers CSV contenant les coordonnées des nouveaux utilisateurs dans PagerDuty PagerDuty de nouvelles équipes rejoignent la plateforme, 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 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 consulter via l'interface web, et leur accès sera limité par les périmètres de l'application que vous développez. La combinaison des autorisations et des périmètres offre un contrôle complet sur les utilisateurs autorisés à consulter et modifier les objets, que ce soit via l'interface 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 workflow se déroulera dans l'interface utilisateur de PagerDuty et l'autre sur votre poste de travail. Pour effectuer 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 . Une partie du workflow de l'application consistera à demander à l'utilisateur de se connecter à PagerDuty. L'application sera alors autorisée à accéder uniquement aux objets accessibles à l'utilisateur connecté, inclus dans les périmètres 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 application d'exemple devra être enregistrée auprès de PagerDuty afin de pouvoir accéder 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 et une description à votre application, 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 correspond à l'emplacement de l'application que vos utilisateurs utiliseront pour accéder aux objets PagerDuty . Il peut être hébergé partout où les utilisateurs peuvent y accéder. Il n'est pas nécessaire qu'il soit accessible publiquement ou à 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 https://localhost:5000/callback . Notez qu'il n'y a pas https ! Ceci n'est qu'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 tester pour votre application. Je vais commencer par Services 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 pour qu'il soit aussi large ou restreint que nécessaire pour les tâches à effectuer. Si vous ne savez pas quelles étendues s'appliquent à quels objets, consultez la section Documentation de l'API .

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

Nouvelle fonctionnalité : Vous pouvez désormais télécharger un json Veuillez déposer votre dossier avec vos identifiants ! Vous n'aurez qu'une seule chance de le faire. Vous recevrez un json fichier avec votre client_id et secret_client Nous en aurons besoin pour configurer notre exemple d'application, alors cliquez 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 client_id et secret_client Pour demander un jeton. Ce processus se déroule en deux étapes : récupérer un code d'autorisation et l'utiliser pour générer un jeton. Les codes d'autorisation ne sont valables que 30 secondes ; il est donc préférable d'effectuer les deux requêtes dans le même outil ou script, même si vous ne développez 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 reçus lors de la création de l'application PagerDuty . Elle présentera à l'utilisateur un écran d'autorisation de connexion, effectuera les requêtes pour moi et me fournira le jeton que je pourrai utiliser pour mes propres requêtes dans des scripts ou avec curl, comme dans les exemples de notre article. 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 pour configurer votre application. Vous utiliserez le contenu du fichier JSON téléchargé depuis l'interface web : client_id et secret_client - dans le config.json déposer:

{

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

« PD_CLIENT_SECRET » : « xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx »,

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

}

Une fois votre config.json Une fois le fichier créé, suivez les étapes restantes pour installer les dépendances de l'application. Selon votre environnement et les versions de Python 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 en cours d'utilisation, vous pouvez effectuer une mise à jour vers un autre port dans le app.py fichier, sur la dernière ligne.

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

Connectez-vous et récupérez votre jeton

Quand app.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 workflow 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 à gérer l'authentification ni l'autorisation ! Laissez PagerDuty s'en charger.

Connectez-vous avec votre nom d'utilisateur 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 « Envoyer le consentement ». Vous serez redirigé vers votre redirect_uri , dans ce cas, le app.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 légèrement le code pour l'afficher 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 à votre disposition pour vos scripts et outils, quel que soit le langage choisi. Intégrez-le à vos requêtes API en tant qu'en-tête « Authorization » :

Autorisation : Porteur pdus+_xxxxxxxxxxxxxxxxxxxxxxxxxxx

Par exemple, voici un script shell pour demander /services :

JETON=$PD_API_KEY

POINT DE TERMINAISON = « 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 services et utilisateurs . Si j'essayais d'utiliser ce jeton pour accéder au /incidents point de terminaison, je recevrais l'erreur suivante :

{« error » : {« 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 porteur que nous avons reçu dans la section précédente n'est valable que 24 heures. Le code de l'exemple d'application ne permet pas d'actualiser les jetons. Il est donc plus simple d'en demander un nouveau : il suffit de revenir à la première URL et de cliquer à nouveau sur le lien « Se connecter à PagerDuty» pour obtenir un nouveau jeton.

Lors de l'intégration de 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 en backend et actualiser les données 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 configuration. Vous pouvez révoquer tous les jetons actifs de l'application, supprimer le client 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 devez 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 déjà utilisé Scoped OAuth dans vos outils ? Dites-le-nous ! Rejoignez-nous Forums communautaires ou contactez community-team@pagerduty.com Nous aimerions savoir ce que vous pensez des nouvelles fonctionnalités et ce que vous espérez voir à l’avenir.

X Facebook LinkedIn

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