Die PagerDuty REST API bietet über 200 Endpunkte, über die Benutzer programmgesteuert auf Objekte und Workflows in der PagerDuty Plattform zugreifen können. Teams nutzen diese APIs, um das Erstellen und Verwalten von Benutzern, Teams, Diensten und anderen Komponenten für ihre Umgebung zu optimieren.

Bisher erfolgte der Zugriff auf die REST-API autorisiert und authentifiziert über API-Schlüssel . Diese Schlüssel werden in der Web-Benutzeroberfläche verwaltet und bieten einen Alles-oder-Nichts-Zugriff auf die Objekte im Konto, was sie für viele Teams zu freizügig macht. Daher hat PagerDuty Engineering an der Erstellung eines umfassenden Satzes von API-Bereichen für die Verwendung mit OAuth2.0-Tokens gearbeitet.

Jedes Objekt in der PagerDuty REST API hat mindestens einen Bereich, lesen und viele Objekte haben auch schreiben . Sie können Ihre Apps so einstellen, dass sie nur die Zugriffsrechte haben, die sie für die ordnungsgemäße Funktion benötigen, ohne sich Sorgen machen zu müssen, dass sie auch auf alles andere in Ihrem Konto zugreifen können.

Für Leute, die derzeit API-Schlüssel verwenden, werden diese vorerst weiterhin funktionieren (achten Sie auf mögliche EOL-Probleme in der Zukunft), aber die Migration zu Bereichsbezogenes OAuth hilft Teams dabei, den Zugriff zu verwalten und das Prinzip der geringsten Privilegien einzuhalten.

Eine Videoeinführung zu API Scopes finden Sie unter Dieses Video auf unserem Youtube Kanal .

App einrichten

Die erste Änderung, die Sie beim Einrichten des API-Zugriffs mit Bereichen bemerken werden, ist, dass der Zugriff über einen App . Diese werden nicht über den Abschnitt „API-Zugriffsschlüssel“ im Menü „Integrationen“ verwaltet. Sie müssen stattdessen zur „App-Registrierung“ (früher bekannt als „Entwicklermodus“) gehen und den App-Konfigurationsprozess durchführen. Das Einrichten dieser ist auf die Administratoren und Eigentümer Ihres Kontos beschränkt.

Wenn die App erstellt ist, haben Sie die Möglichkeit, ihr Scoped OAuth hinzuzufügen:

Bei Apps, die Scoped OAuth unterstützen, können Sie im nächsten Dialogfeld auswählen, welche Objekte für Token verfügbar sein sollen, die aus diesem App-Zugriff abgeleitet werden. Sie können so viele oder so wenige auswählen, wie für Ihren Anwendungsfall angemessen sind:

Nach dem Klicken Speichern wird ein Popover-Fenster mit zwei wichtigen Informationen angezeigt: Kunden ID Und Geheimer Clientschlüssel die zum Bereitstellen von Token für den Zugriff auf diese App verwendet werden.

Sie benötigen diese zum Bereitstellen von Token. Speichern Sie sie daher in einem Tresor oder an einem anderen Ort oder in einer App, die Sie für Zertifikate, Passwörter oder Geheimnisse verwenden.

Bereiche finden

Wie Sie dem obigen Screenshot entnehmen können, gibt es viele mögliche Bereiche, die Ihre Token benötigen könnten, je nachdem, auf welche Objekte über die API zugegriffen wird.

Glücklicherweise API-Dokumentation wurde aktualisiert, um die erforderlichen Bereiche für alle Objektendpunkte einzuschließen. Jeder Anforderungstyp verfügt über eine Anmerkung, die den Bereich enthält und angibt, ob die Anforderung Lese- oder Schreibzugriff erfordert. Generell gilt jedoch, dass Anforderungen mit GET-Methoden – die zum Auflisten oder Abrufen von Informationen verwendet werden – nur Lesezugriff erfordern, während PUT-, POST- und DELETE-Anforderungen Schreibzugriff erfordern.

Token anfordern

Token, die mit dem Scoped Client in Ihrer App verknüpft sind, werden angefordert von https://identity.pagerduty.com/oauth/token Verwenden Sie die Anmeldeinformationen, die Sie beim Erstellen der App erhalten haben. Das Anforderungsformat finden Sie in den API-Dokumenten Hier . Die anderen erforderlichen Daten sind Ihre Region (USA oder EU) und Subdomäne (IhrKonto.pagerduty.com). Jedes angeforderte Token muss angeben, für welche Bereiche es gültig ist.

 curl -i --request POST \ 

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

 --header 'Inhaltstyp: Anwendung/x-www-form-urlencoded' \ 

 --data-urlencode 'Grant_Type=Client-Anmeldeinformationen' \ 

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

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

 --data-urlencode 'Bereich=as_account-us.companysubdomain Vorfälle.read Dienste.read' 

Die in einem Token enthaltenen Bereiche können der vollständige Satz der in der App enthaltenen Bereiche oder eine Teilmenge dieser Bereiche sein, je nachdem, wie Ihre Organisation die Token verwalten möchte. Die Token werden in einem JSON-Dokument zurückgegeben:

 { 

 'Zugriffstoken': 'pdus+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 

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

 'token_type': 'Träger', 

 'läuft ab in': 2592000 

 } 

Diese Token haben eine Ablauffrist! Dies ist eine große Änderung gegenüber den nie ablaufenden API-Schlüsseln. Token müssen alle 24 Stunden ausgetauscht werden.

Um außerdem Leuten mit Repository-Scannern dabei zu helfen, sicherzustellen, dass Token nicht eingecheckt werden, beginnt jeder PagerDuty Token mit „pd<region> +“, also entweder pdus+ oder pdeu+ damit die Token leicht identifiziert werden können.

Sobald ein Token erstellt wurde, liegt es an Ihnen, wie er verteilt und verwaltet wird. Die Token werden nicht in der Web-Benutzeroberfläche aufgelistet oder sind anderweitig auf der Plattform verfügbar. Auf der App-Seite können Sie alle mit der App verknüpften Token widerrufen, jedoch nicht einzelne.

Token verwenden

Wenn Sie über benutzerdefinierte Skripts auf die API zugegriffen haben, müssen Sie einige Aktualisierungen durchführen, um die neuen Token verwenden zu können.

Für Shell-Skripte, die Kommandozeilen-Tools verwenden wie Locke oder wget Um ihre HTTPS-Anfragen zu stellen, müssen Sie die Genehmigung Header:

 --header 'Autorisierung: Inhaber $TOKEN' 

In ähnlicher Weise möchten Sie in Tools wie Postman die Autorisierung auf ein Bearer-Token setzen. Weitere Informationen dazu in Postman finden Sie im Postman-Dokumentation .

Wenn Sie eine der verschiedenen Client-Bibliotheken für die API von PagerDuty verwenden, überprüfen Sie die Dokumentation für diese Projekte, um festzustellen, ob eine Codeänderung erforderlich ist. Beispielsweise in Abonnieren ist ein Sitzungskonstruktor speziell für OAuth2.0-Token verfügbar:

 # REST-API v2 mit einem OAuth2-Zugriffstoken: 

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

Abhängig von den von Ihnen verwendeten Programmiersprachen sind möglicherweise ausgefeiltere Lösungen oder Unterstützung für OAuth2.0-Token verfügbar. Beispielcode für mehrere Sprachen ist auch im Dokumentation auf der Entwicklerseite.

Token und Apps verwalten

Wie Sie die Granularität Ihrer App und Token gestalten, hängt von Ihnen und den Sicherheitsanforderungen Ihrer Organisation ab. Es gibt einige empfohlene Methoden, die Ihnen den Einstieg erleichtern.

Wer stellt Token bereit?

Da die Scoped OAuth-Token eine Gültigkeit von 30 Tagen haben, wird es für Organisationen mit vielen Teams, die programmgesteuert auf die PagerDuty API zugreifen, wahrscheinlich einfacher sein, die Kunden ID Und Client-Geheimnis mit einzelnen Teams und ermöglichen ihnen die Bereitstellung eigener Token. Administratoren können Apps für jedes Team oder jeden Anwendungstyp erstellen, um zu steuern, wer Zugriff auf die API und welche Objekte hat.

Kleinere Teams oder solche, die mehr Kontrolle über den Zugriff auf Ressourcen benötigen, möchten möglicherweise die Kunden ID Und Client-Geheimnis an die Kontoadministratoren, die dann Token erstellen und über einen sicheren Speicher an die Teams weitergeben.

Apps mit vollem Umfang, Token mit begrenztem Umfang

Für Anwendungsfälle, die Zugriff auf viele verschiedene Objekte erfordern, können Sie die App so einrichten, dass sie alle Bereiche umfasst. Da Token mit einer Teilmenge aller zulässigen Bereiche angefordert werden können, können einzelne Token auf das beschränkt werden, was die Clientanwendung in der API verwenden wird.

Mit dieser Methode lässt sich die Anzahl der Apps reduzieren, die im PagerDuty Konto verwaltet werden müssen. Administratoren können Apps für Teams oder Abteilungen bereitstellen und Token mit eingeschränkterem Umfang bereitstellen.

Probieren Sie es aus und lassen Sie es uns wissen

Scoped OAuth ist jetzt als Early-Access-Funktion verfügbar und wird Ende Mai 2023 für alle Konten allgemein verfügbar sein. Probieren Sie es aus und teilen Sie uns Ihre Meinung mit! Melden Sie sich für den Early Access an unter https://www.pagerduty.com/early-access/ oder kontaktieren Sie Ihr Account-Team, um mehr zu erfahren. Sie können auch unserem Gemeinschaftsforum wenn du Fragen hast.