Der Blog

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

von Mandi Walls 26. Oktober 2023 | 9 Minuten Lesezeit

Viele PagerDuty -Kunden erstellen eigene Apps zur Verwaltung ihrer PagerDuty Umgebungen. Teams verfügen möglicherweise über zahlreiche Workflows, die von einer benutzerdefinierten Anwendung profitieren könnten. Ein PagerDuty Administrator möchte beispielsweise CSV-Dateien mit neuen Benutzern und deren Kontaktdaten in PagerDuty laden können, wenn neue Teams der Plattform beitreten, oder neue Dienste laden, bevor diese in die Produktion gehen. Benutzerdefinierte Anwendungen für PagerDuty können diese Verwaltungsaufgaben erleichtern, wenn eine weitere 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. Ihr Zugriff wird zudem 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 erfolgt in der PagerDuty -Benutzeroberfläche, ein Teil auf Ihrem Arbeitsplatzrechner. Um alle Schritte auszuführen, benötigen Sie Administratorrechte für Ihr PagerDuty -Konto und müssen Python-Apps auf Ihrem Arbeitsplatzrechner ausführen können.

Wir erstellen eine App als PagerDuty Administrator. Teil des App-Workflows ist die Aufforderung an den Benutzer, sich bei PagerDuty anzumelden. Die App ist dann nur für den Zugriff auf Objekte berechtigt, die für den angemeldeten Benutzer zugänglich sind und in den Anwendungsbereichen der App enthalten sind.

Registrieren einer Anwendung

Dieser Arbeitsablauf ähnelt dem, den wir im vorherigen 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 Entwicklerdokumente .

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

Öffnen Sie in Ihrem PagerDuty -Konto die Integrationen Menü oben auf dem Bildschirm und klicken Sie auf App-Registrierung im Entwicklertools 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; belassen Sie diese Option. Im nächsten Abschnitt fügen wir eine „Umleitungs-URL“ für unsere Beispiel-App hinzu. Im OAuth-Flow ist der Rückruf der Speicherort der Anwendung, die Ihre Benutzer für den Zugriff auf PagerDuty Objekte verwenden. Er kann überall gehostet werden, wo Benutzer darauf zugreifen können. Er muss weder öffentlich verfügbar noch 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/callback . Beachten Sie, dass es keine https ! Dies ist nur eine Beispiel-App und nicht für die Produktion gedacht.

Wählen Sie anschließend die Objekte und den Zugriffstyp aus, die Sie für Ihre App ausprobieren möchten. Ich beginne mit Leistungen 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!! Apps, die Sie erstellen, benötigen diesen Zugriff möglicherweise nicht! Sie können den Zugriff so weit oder eng konfigurieren, wie Sie ihn für die 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 weiterhin nur eine Möglichkeit dazu. Sie erhalten eine json Datei mit Ihrem Client-ID Und Client-Geheimnis darin. Wir benötigen diese, um unsere Beispiel-App zu konfigurieren, also klicken Sie 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 Client-ID Und Client-Geheimnis um ein Token anzufordern. Dies ist ein zweistufiger Prozess: Rufen Sie einen Autorisierungscode ab und verwenden Sie diesen Code zum Generieren eines Tokens. Autorisierungscodes sind nur 30 Sekunden gültig. Daher sollten Sie beide Anfragen wahrscheinlich im selben Tool oder Skript stellen, auch wenn Sie keine vollständige Anwendung schreiben.

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

Ich werde das Python-Beispiel mit ein paar Anpassungen verwenden. Es handelt sich um eine recht einfache Flask-App, die die Autorisierungselemente verwendet, die wir beim Erstellen der PagerDuty -App erhalten haben. Sie präsentiert dem Benutzer einen Anmeldebildschirm, stellt die Anfragen für mich und gibt mir das Token, 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 Client-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 Nachdem die Datei erstellt wurde, führen Sie die restlichen Schritte zur Installation der App-Abhängigkeiten aus. 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 Ihrer app.py-Anwendung ändern müssen, müssen Sie zu den Konfigurationsschritten in der Benutzeroberfläche zurückkehren und Ihre Weiterleitungs-URI ändern. Speichern Sie unbedingt alle Änderungen!

Anmelden und Token abrufen

Wann app.py läuft, 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 dienen zur Autorisierung. Ihre Anwendung muss weder Authentifizierung noch Autorisierung übernehmen! Ü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 „Einwilligung ü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 der Seite auszudrucken. 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 Ihrer gewünschten Sprache zur Verfügung. Integrieren Sie es als „Authorization“-Header in Ihre API-Anfragen:

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.lesen“,“Token_Bereiche“:“OpenID-Dienste.lesen Benutzer.lesen“}}

Timeouts und Aktualisierung

Im Gegensatz zu unseren API-Schlüsseln haben OAuth-Token eine begrenzte Lebensdauer. Der Inhaber-Token, den wir im letzten Abschnitt erhalten haben, ist nur 24 Stunden gültig. Der Code der Beispiel-App bietet keine Option zum Aktualisieren von Token. Daher ist die Anforderung eines neuen Tokens am einfachsten. Kehren Sie einfach zur ersten URL zurück und klicken Sie erneut auf den Link „Mit PagerDuty verbinden“, um einen neuen Token zu erhalten.

Wenn Sie diesen Flow 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 Kunde 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 , gelangen Sie zurück zum Hauptbildschirm App bearbeiten Bildschirm. Um einen neuen Client OAuth für Ihre Anwendung zu erstellen, fügen Sie erneut OAuth 2.0 zu Ihrer Bewerbung auf die gleiche Weise wie oben.

Wenn Ihr Team eine App nicht mehr benötigt, können Sie die gesamte App jetzt von 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 .

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

Teilen Sie uns Ihre Meinung mit!

Nutzen Sie Scoped OAuth bereits in Ihren Tools? Lassen Sie es uns wissen! Werden Sie Teil 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.

X Facebook LinkedIn

Das könnte Ihnen auch gefallen ...