Der Blog

Erstellen Sie anspruchsvolle Apps für Ihre PagerDuty Umgebung mit OAuth 2.0 und API-Bereichen

von Mandi-Wände 26. Oktober 2023 | 9 min lesen

Viele PagerDuty -Kunden erstellen eigene Apps, die ihnen bei der Verwaltung ihrer PagerDuty Umgebungen helfen. Teams haben möglicherweise eine beliebige Anzahl von Workflows, die von einer benutzerdefinierten Anwendung profitieren könnten. Ein PagerDuty -Administrator möchte möglicherweise CSV-Dateien mit neuen Benutzern und ihren Kontaktinformationen in PagerDuty laden können, wenn neue Teams der Plattform beitreten, oder neue Dienste laden, bevor sie in die Produktion freigegeben werden. Das Erstellen benutzerdefinierter Anwendungen für PagerDuty kann bei diesen Verwaltungsaufgaben hilfreich sein, wenn eine andere Komponente das System of Record für diese Daten ist.

Im Mai haben wir uns angesehen Aktualisieren benutzerdefinierter Tools für API-Bereiche vs. PagerDutys Original API-Schlüssel , und die Anwendung selbst verwendet, um die Token anzufordern (über einige Skripte), aber Entwickler können Benutzern auch erlauben, sich bei einer App anzumelden und sich gegenüber PagerDuty selbst zu authentifizieren, um zu steuern, welche Objekte verfügbar sein werden.

Angemeldete Benutzer haben nur Zugriff auf die Objekte, die sie auch über die Web-Benutzeroberfläche sehen können, und ihr Zugriff wird auch durch die Bereiche der von Ihnen erstellten Anwendung eingeschränkt. Die Kombination aus Berechtigungen und Bereichen bietet umfassende Kontrolle darüber, welche Benutzer welche Objekte sehen und ändern können, sei es über die Web-Benutzeroberfläche, die API oder benutzerdefinierte Apps.

Wir verwenden ein Beispielanwendung die unser Engineering-Team als Beispiel veröffentlicht hat.

Ein Teil des Workflows wird in der PagerDuty Benutzeroberfläche ausgeführt, ein Teil auf Ihrer Workstation. Um alle Schritte auszuführen, müssen Sie Administrator Ihres PagerDuty Kontos sein und Python-Apps auf Ihrer Workstation ausführen können.

Wir erstellen eine App als PagerDuty Administrator. Ein Teil des Workflows der App selbst besteht darin, den Benutzer aufzufordern, sich bei PagerDuty anzumelden. Die App ist dann nur berechtigt, auf Objekte zuzugreifen, auf die der angemeldete Benutzer zugreifen kann und die in den Bereichen für die App enthalten sind.

Registrieren einer Anwendung

Dieser Arbeitsablauf ähnelt dem, den wir im früheren Blogbeitrag gesehen haben, aber es gibt eine neue Funktion, die die Dinge einfacher macht!

Unsere Beispiel-App muss bei PagerDuty registriert werden, um Zugriff auf PagerDuty Objekte zu ermöglichen. Eine detaillierte Beschreibung des App-Registrierungsprozesses finden Sie im Entwickler-Dokumente .

Nur Kontoadministratoren können Anwendungen mit den Scoped OAuth 2.0-Funktionen erstellen. (Reguläre Benutzer können weiterhin ihre eigenen Anwendungen erstellen, aber die Funktionen sind beschränkt auf Klassisches Benutzer-OAuth .)

Öffnen Sie in Ihrem PagerDuty -Konto das Integrationen Menü oben auf dem Bildschirm und klicken Sie auf App-Registrierung im Entwicklerwerkzeuge Spalte. Fügen Sie mit der Schaltfläche rechts eine neue App hinzu oder aktualisieren Sie eine vorhandene App.

Geben Sie Ihrer App einen Namen und eine Beschreibung, wählen Sie „OAuth 2.0“ und klicken Sie dann auf „Weiter“:

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.

Auf der nächsten Seite ist standardmäßig „Scoped OAuth“ ausgewählt; lassen Sie diese Option ausgewählt. Im nächsten Abschnitt möchten wir eine „Umleitungs-URL“ für unsere Beispiel-App hinzufügen. Im OAuth-Flow ist der Rückruf der Speicherort der Anwendung, die Ihre Benutzer verwenden, um auf PagerDuty Objekte zuzugreifen, und kann überall gehostet werden, wo Benutzer darauf zugreifen können. Er muss nicht öffentlich verfügbar oder für PagerDuty zugänglich sein.

Unsere Beispiel-App ist so konzipiert, dass sie standardmäßig lokal auf Ihrer Workstation ausgeführt wird. lokaler Host . Konfigurieren Sie Ihre Weiterleitungs-URL für http://localhost:5000/Rückruf . Beachten Sie, dass es keine https ! Dies ist nur eine Beispiel-App und nicht für die Produktion gedacht.

Wählen Sie als Nächstes die Objekte und den Zugriffstyp aus, die Sie für Ihre App ausprobieren möchten. Ich beginne mit Dienstleistungen aber mach es Lesezugriff nur:

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

Damit unsere Beispiel-App funktioniert, müssen Sie auch Lesezugriff für das Benutzerobjekt hinzufügen!! Von Ihnen erstellte Apps benötigen diesen Zugriff möglicherweise nicht! Sie können den Zugriff so weit oder eng konfigurieren, wie Sie ihn für die von Ihnen zu erledigenden Aufgaben benötigen. Wenn Sie nicht sicher sind, welche Bereiche für welche Objekte gelten, lesen Sie die API-Dokumentation .

Wenn Sie Ihre Bereiche ausgewählt haben, klicken Sie auf das App registrieren Schaltfläche unten auf dem Bildschirm.

Neue Funktion : Sie können jetzt eine json Datei mit Ihren Anmeldeinformationen! Sie haben dennoch nur eine Gelegenheit dazu. Sie erhalten eine json Datei mit Ihrem Kunden ID Und Client-Geheimnis darin. Wir benötigen diese, um unsere Beispiel-App zu konfigurieren, also klicken Sie auf JSON herunterladen und dann Weitermachen .

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.

Verwenden einer Beispiel-App zum Abrufen eines neuen Benutzertokens

Sobald Sie Ihre App registriert haben und die Autorisierungs-JSON-Datei erhalten haben, können Sie die Kunden ID Und Client-Geheimnis um ein Token anzufordern. Dies ist ein zweistufiger Prozess: Rufen Sie einen Autorisierungscode ab und verwenden Sie diesen Code, um ein Token zu generieren. Autorisierungscodes sind nur 30 Sekunden lang gültig, daher sollten Sie beide Anfragen wahrscheinlich in dasselbe Tool oder Skript eingeben, auch wenn Sie keine vollständige Anwendung schreiben.

Sie können auch eines unserer Muster verwenden, zum Beispiel Python oder Javascript / Node.js .

Ich werde das Python-Beispiel mit ein paar Anpassungen verwenden. Es ist eine ziemlich einfache Flask-App, die die Autorisierungselemente verwendet, die wir beim Erstellen der PagerDuty -App erhalten haben, dem Benutzer einen Anmeldeautorisierungsbildschirm präsentiert, die Anfragen für mich stellt und mir das Token gibt, das ich für meine eigenen Anfragen in Skripten oder mit curl verwenden kann, ähnlich wie die Beispiele in unserem früherer Beitrag .

Herunterladen, Konfigurieren und Ausführen der Beispiel-App

Befolgen Sie die Anweisungen in der Beispiel-App README.md Datei, um Ihre App zu konfigurieren. Sie verwenden den Inhalt der JSON-Datei, die Sie von der Web-Benutzeroberfläche heruntergeladen haben – die Kunden ID Und Client-Geheimnis - im config.json Datei:

{

„PD_CLIENT_ID“: „xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx“,

„PD_CLIENT_SECRET“: „xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx“,

„REDIRECT_URI“: „http://localhost:5000/callback“

}

Sobald Ihr config.json Datei erstellt wurde, führen Sie die restlichen Schritte aus, um die App-Abhängigkeiten zu installieren. Abhängig von Ihrer Umgebung und den installierten Python-Versionen müssen Sie möglicherweise die python3 Befehl:

  • Erstellen Sie eine virtuelle Umgebung für Python: python -m venv env
  • Aktivieren Sie die Umgebung: Quellumgebung/bin/aktivieren
  • Installieren Sie Abhängigkeiten: pip install -r Anforderungen.txt
  • Führen Sie die App aus: Python-App.py

Wenn Sie eine Fehlermeldung erhalten, dass der Port bereits verwendet wird, können Sie im app.py Datei, in der letzten Zeile.

Hinweis: Wenn Sie den Port verschieben müssen, auf dem Ihr app.py ausgeführt wird, müssen Sie zu den Konfigurationsschritten in der Benutzeroberfläche zurückkehren und Ihre Umleitungs-URI ändern. Denken Sie daran, alle Ihre Änderungen zu speichern!

Melden Sie sich an und rufen Sie Ihr Token ab

Wann app.py ausgeführt wird, können Sie die URL in Ihrem Browser öffnen und sich bei PagerDuty anmelden:

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

Wenn Sie auf den Link „Mit PagerDuty verbinden“ klicken, werden Sie auf eine Anmeldeseite weitergeleitet, die auf identity.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.

Dieser Workflow schützt Ihr Konto. Ihr Team meldet sich direkt bei PagerDuty an und die Token werden zur Autorisierung verwendet. Ihre Anwendung muss weder Authentifizierung noch Autorisierung durchführen! Überlassen Sie das PagerDuty .

Melden Sie sich mit Ihrem Benutzernamen und Passwort an. PagerDuty fordert Sie auf, die App für Ihr Konto zu autorisieren:

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

Klicken Sie auf „Zustimmung übermitteln“. Sie werden zurück zu Ihrem Umleitungs-URI , in diesem Fall die app.py An lokaler Host .

Ihr Token ist Teil der Informationen, die an die App zurückgegeben werden, und ist Teil der Körper der Rückgabedaten. Sie können den Code ein wenig ändern, um ihn auf die Seite zu drucken. Ich habe hinzugefügt Zeichen Und Aktualisierungstoken zu meiner Ausgabe als Beispiel:

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.

Dieses Token steht Ihnen nun zur Verwendung in Skripten und Tools in der von Ihnen gewählten Sprache zur Verfügung. Integrieren Sie es in Ihre API-Anfragen als „Authorization“-Header:

Autorisierung: Träger pdus+_xxxxxxxxxxxxxxxxxxxxxxxxxxx

Hier ist beispielsweise ein Shell-Skript zum Anfordern /Dienstleistungen :

TOKEN=$PD_API_KEY

ENDPOINT=”Dienste”

curl -X GET –header 'Inhaltstyp: application/json' \

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

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

–header „Autorisierung: Inhaber $TOKEN“

Nicht autorisierte Bereiche

Da unser Token einen sehr engen Anwendungsbereich hat, wird ein Fehler angezeigt, wenn Sie versuchen, damit auf etwas anderes zuzugreifen als Dienstleistungen Und Benutzer . Wenn ich versuche, mit diesem Token auf die /Vorfälle Endpunkt, würde ich den folgenden Fehler erhalten:

{„Fehler“:{„Nachricht“:“Für das Token fehlen die erforderlichen Bereiche“,”erforderliche_Bereiche“:“Vorfälle.read“,”Token_Bereiche“:“OpenID-Dienste.read Benutzer.read“}}

Timeouts und Aktualisierung

Im Gegensatz zu unseren API-Schlüsseln haben OAuth-Token eine begrenzte Lebensdauer. Das Inhabertoken, das wir im letzten Abschnitt erhalten haben, ist nur 24 Stunden lang gültig. Der Beispiel-App-Code bietet keine Option zum Aktualisieren von Token, daher ist es am einfachsten, ein neues Token anzufordern. Kehren Sie einfach zur ersten URL zurück und klicken Sie erneut auf den Link „Mit PagerDuty verbinden“, um ein neues Token zu erhalten.

Wenn Sie diesen Ablauf in eine andere App integrieren, sollten Sie das Aktualisierungstoken verwenden, damit sich Benutzer nicht immer wieder anmelden müssen. Sie können ihr Konto autorisieren und Ihre Anwendung kann die Token im Backend verwalten und bei Bedarf aktualisieren. Weitere Informationen zur Verwendung der Aktualisierungstoken finden Sie im Dokumente .

Token widerrufen und Anwendungen löschen

Wenn Sie die Token für eine Anwendung widerrufen müssen, können Sie dies auf der Klient Panel der Konfigurationsseite. Sie können alle aktiven Token für die Anwendung widerrufen, den Client selbst löschen und ein neues Geheimnis generieren.

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

Wenn Sie Client OAuth aus Ihrer Anwendung löschen, müssen Sie Ihren gesamten Code aktualisieren, der möglicherweise diese Anwendungskonfiguration verwendet, um mit PagerDuty zu kommunizieren.

Nachdem Sie geklickt haben Löschen , Sie werden zum Hauptbildschirm zurückgeführt App bearbeiten Bildschirm. Um einen neuen Client OAuth für Ihre Anwendung zu erstellen, fügen Sie erneut hinzu OAuth 2.0 zu Ihrer Bewerbung in der gleichen Weise wie oben.

Wenn Ihr Team eine App nicht mehr benötigt, können Sie die gesamte App jetzt aus Ihrem App-Registrierung Seite:

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.

Klicken Sie einfach auf das Drei-Punkte-Menü auf der rechten Seite der App-Liste und wählen Sie Löschen .

Beim Löschen der App werden alle Geheimnisse und widerruft alle Token .

Lass uns wissen was du denkst!

Haben Sie bereits begonnen, Scoped OAuth in Ihren Tools zu verwenden? Lassen Sie es uns wissen! Werden Sie Mitglied unseres Community-Foren oder wenden Sie sich an community-team@pagerduty.com . Wir würden gerne hören, was Sie von den neuen Funktionen halten und was Sie sich für die Zukunft wünschen.

Facebook LinkedIn Þjórsárden

Das könnte Ihnen auch gefallen ...