damios Blogs Pewn API Autorisierung
Pewn API Autorisierung 05.08.2016 - 12:47 4
Folgenden Nutzern gefällt das Design: krazun, Michael, Ikarus, alistez

Mit dem letzten Update ist die Pewn API um eine OAuth-Integration erweitert worden. Das bedeutet, dass es externen Anwendungen nun auch möglich ist, schreibend über die API auf Pewn zuzugreifen.

Im Folgenden werde ich näher erläutern, wie die Autorisierung abläuft und im Anschluss von externen Anwendungen genutzt werden kann.

 

Anwendung einrichten

Um eine Anwendung (einen Clienten) zu registrieren, muss die Beta-Funktion im Profil aktiviert sein. In der API Dokumentation (im Footer) findet sich dann unter „Meine Anwendungen“ die Option, eine neue Applikation zu erstellen.

Hier können vier Dinge festgelegt werden:

  • Name: Der Name der Anwendung, z.B. „Login - Spiel XY“; kann nachträglich nicht geändert werden
  • Beschreibung: Eine kurze Beschreibung der Anwendung, damit der Nutzer über den Zweck der Anwendung Bescheid weiß
  • Redirect-URI: Die Adresse, auf die der Nutzer nach der Autorisierung der Anwendung mit dem Auth-Code als Query-Parameter umgeleitet wird. Wenn das Feld freigelassen wird, wird dem Nutzer der Auth-Code direkt angezeigt, sodass er ihn kopieren kann. Weiteres dazu folgt bei den Ausführungen zum Ablauf.
  • Die Zugriffsberechtigungen:  Eine Liste aller Berechtigungen findet sich hier. Die ausgewählten Berechtigungen können zur Zeit nicht nachträglich geändert werden. Sollte das allerdings von gesteigertem Interesse sein, werde ich das sobald wie möglich in Angriff nehmen.

 

Der Ablauf der Autorisierung (OAuth2)

1. Die externe Anwendung möchte Zugriff auf die Daten eines Nutzers erhalten, bzw. den Nutzer authentifizieren.

2. Dazu leitet die Anwendung den Nutzer auf Pewn um. Zielpunkt auf Pewn ist der Auth-Endpunkt:

/auth/?response_type=code&client_id=12345

Als Query-Parameter müssen angehängt sein:

            client_id -> Die ID der Anwendung (Unter „Meine Anwendungen“ zu finden)

            response_type -> Zur Zeit wird nur 'code' unterstützt

3. Dem Nutzer werden nach dem Anmelden alle Berechtigungen gezeigt, die die Anwendung fordert. Mit einem Klick auf „Zugriff erlauben“ autorisiert er die Anwendung.

4. Daraufhin wird er zurück zur Anwendung geleitet und zwar auf die zuvor hinterlegte Redirect-URI. Als Query-Parameter ist der Auth-Code angehängt. Wenn keine Redirect-URI hinterlegt ist, wird der Code so angezeigt, dass der Nutzer ihn kopieren kann.

5. Der Auth-Code kann von der Anwendung dann innerhalb von 10 Minuten am Token-Endpunkt (/api/v1/oauth/token) gegen einen Access-Token und einen Refresh Token ausgetauscht werden. Dazu muss der Client eine POST-Anfrage an den Endpunkt senden und folgenden Parameter im Request-Body haben:

            client_id -> Die ID der Anwendung

            client_secret -> Der anwendungsspezifische API-Key (auch unter „Meine Anwendungen“ zu finden)

            grant_type -> 'authorization_code'

            code -> Der zuvor erhaltene Auth-Code

            redirect_uri -> Muss zwar angehängt werden, der Wert ist aber irrelevant. Muss in Zukunft identisch mit der hinterlegten URI sein.

 

Als Antwort liefert die API folgendes:

{

          "access_token": "37dcde80-4523-42c1-be10-4f76af272d9a",

          "refresh_token": "60ce2505-c436-4316-ba03-2a93cdfd15df",

          "token_type": "Bearer",

          "expires_in": 3600,

          "username": "test"

}

 

Der Access-Token ist für 60 Minuten gültig und kann verwendet werden, um auf geschützte Ressourcen zuzugreifen. Mehr dazu im AbschnittZugriff auf geschützte Ressourcen“.

Der Refresh-Token sollte von der Anwendung sicher verwahrt werden, denn er ist unbegrenzt gültig und kann jederzeit zum Anfordern eines neuen Access-Tokens verwendet werden. Dazu muss nur eine POST-Anfrage an den Token-Endpunkt gesendet werden, die folgende Parameter im Request-Body enthält:

            client_id -> Die ID der Anwendung

            client_secret -> Der anwendungsspezifische API-Key

            grant_type -> 'refresh_token'

            refresh_token -> Der Refresh-Token

Dadurch wird der alte Access-Token (wenn er noch nicht abgelaufen ist) ungültig, da es pro Client und User nur jeweils einen gültigen Access-Token gibt.

 

Zugriff auf geschützte Ressourcen

Zur Zeit gibt es erst eine API-Methode, die eine vorige Nutzer-Autorisierung erfordert, in (näherer) Zukunft wird da allerdings noch einiges folgen.

/api/v1/self/details

Über diesen Endpunkt kann ein Spiel oder jede andere externe Anwendung auf die E-Mail-Adresse eines Nutzers zugreifen. Dafür erforderlich ist nur, dass die Anwendung im Request-Header einen gültigen Access-Token liefert.

 

Für Fragen stehe ich jederzeit, auch per PN bereit.

 

 

Wichtiger Hinweis

Solange das SSL-Zertifikat noch nicht eingebunden ist, sollten die API-Authentifizierung ausschließlich zum Testen verwendet werden! Nach dem Einbinden werden aus Sicherheitsgründen alle bereits erstellten Anwendungen wieder gelöscht.

 

Weiterführende Links


Aktualisiert: 05.07.2017 - 18:32
Grund:
Kommentar als Gast hinzufügen