PORTAL und PPS Knowledge Base

OAuth-Login über PORTAL

Owned by Former user (Deleted), created
Last updated: 2024-11-12 by Ilker Oygün
4 min read

Das OAuth-Login über PORTAL ermöglicht es Benutzer:innen, sich über ihre Login-Daten im PORTAL in einem externen System zu authentifizieren. Das PEIQ PORTAL ist dabei der Server, bei dem über einen OAuth-Workflow eine Anwendung (Client) die Daten des Benutzers bzw. der Benutzerin zur Authentifizierung beantragt.

Funktionalitäten des OAuth-Logins über das PORTAL

  • Authentifizierung in einem externen System über das PORTAL

  • Abgleich der benutzerbezogenen Zugangsdaten mit den hinterlegten Daten im PORTAL

Inhaltsverzeichnis

Allgemeine Beschreibung

Der OAuth-Login über das PORTAL ermöglicht einen OAuth-Workflow, bei welchen das PORTAL als Server fungiert und Daten zur Nutzung in einem externen System authentifiziert. Mit OAuth beantragt eine Anwendung (Client) mithilfe der benutzerbezogenen Zugangsdaten die Daten der Benutzer:innen beim Server und verarbeitet diese in der eigenen Datenbank.

 

Der OAuth-Login über das PORTAL wird für folgende Funktionen verwendet:

Workflow

  1. Beim Login wird dem/der Benutzer:in die Möglichkeit gegeben, sich mit dem PORTAL anzumelden.

  2. Sofern der/die Benutzer:in noch nicht am PORTAL angemeldet ist, öffnet sich das PORTAL-OAuth-Formular mit der URL https://example.com/oauth/v2/auth_login, in welches der/die Benutzer:in seine/ihre PORTAL-Nutzerdaten (E-Mail + Passwort) eingibt. Eingeloggte PORTAL-Benutzer:innen werden sofort zur entsprechenden Redirect-URL weitergeleitet.

  3. Beim erstmaligen Login muss der/die Benutzer:in zunächst die Anwendung für die Nutzung seiner/ihrer PORTAL-Daten authentifizieren. Bereits hinterlegte Authentifizierungen kann der/die Benutzer:in im PORTAL unter den Account-Einstellungen einsehen und editieren.

  4. Nach Abschicken des Formulars wird ein Token zurückgegeben, mit welchem der/die Benutzer:in authentifiziert werden kann.

    • Nach der erfolgreichen Authentifizierung ist der/die Benutzer:in angemeldet. Es erfolgt eine Weiterleitung zur entsprechenden Redirect-URL.

    • Bei einer fehlgeschlagenen Authentifizierung erhält der/die Benutzer:in eine Fehlermeldung.

Ansicht des PORTAL-OAuth-Formulars

 

 

 

Token

Token-Beispiel für Benutzer “Max Power”, mit der E-Mail-Adresse “root@example.com”:

object(ggm\Connect\DataNodes\UserInfo)#5 (4) { ["id":protected]=> int(1) ["firstName":protected]=> string(3) "Max" ["lastName":protected]=> string(5) "Power" ["email":protected]=> string(16) "root@example.com" }

Implementierungshilfe für Entwickler:innen

Bei der PEIQ OAuth-API handelt es sich um eine Implementierung nach dem OAuth V2 Standard. Auf die Details des Protokolls wird im Folgenden nicht eingegangen, stattdessen wird anhand von Beispielen demonstriert, wie die API zum Anfordern von Access Token verwendet werden kann.

client_credentials

Datenstruktur AccessToken (client_credentials)

{ "access_token": <string>, // Das Access Token "expires_in": <int>, // Zeitraum in Sekunden, die das Token gültig ist "token_type": <string>, // i.d.R. "bearer" "scope": <string> // Liste der zugewiesenen Scopes, mit Leerzeichen getrennt }

Workflow

Das Anfordern von Access Token über die Methode client_credentials erfordert eine Client ID und
ein Secret. Diese können über die Admin-Funktion API Zugänge verwalten selbst generiert werden. Falls diese Funktion nicht freigeschaltet ist, muss der Zugang von PEIQ erstellt werden. In diesem Fall bitte an das PEIQ Support Team wenden.

Die Methode ähnelt dem Benutzer:innen-Login mit Benutzername und Passwort, es wird aber keine
Session initialisiert und das Access Token ist auch nicht an ein:e Benutzer:in gebunden.

Da die Access Token mit System-Rechten ausgestattet und dementsprechend sehr mächtig sind, sollten sie niemals das Backend verlassen oder über unsichere Wege verschickt werden.

Methode:

[GET] /token

Parameter:

  • grant_type Muss immer den Wert client_credentials haben

  • client_id Die Client / Public ID

  • client_secret Das Secret (Passwort)

Rückgabewert:

  • Eine AccessToken Datenstruktur (siehe oben).

Es wird bei jedem GET Request ein neues Token erstellt, auch wenn das zuvor angeforderte noch gültig ist. Um unnötige Requests zu vermeiden, sollten einmal angeforderte Token trotzdem so lange verwendet werden, wie sie gültig sind.

authorization_code

Datenstruktur AccessToken (authorizationcode / refreshtoken)

{ "token": <string>, // Das Access Token "refreshToken": <int>, // Das Refresh Token "expiresAt": <int>, // Aublauf-Datum als UNIX Timestamp "scope": [<string>] // Liste der zugewiesenen Scopes }

Workfow

OAuth Login Zugriffe mit der authorization_code Methode dienen der Implementierung einer "Anmelden mit ..."-Funktion, bei der Benutzer:innen sich mit einem PEIQ PORTAL-Account bei einem Drittdienst anmelden können. Der Workflow entspricht weitestgehend dem generischen OAuth2 Login Workflow.

  1. Öffnen des Login Formulars in einem Pop-up bzw. weiteren Fenster

  2. Auswerten des Authorization Codes

  3. Access Token mithilfe des Authorization Codes erstellen

Anmerkungen:

  • state dient der Absicherung von einzelnen Authorization Requests und sollte innerhalb eines Workflows immer auf Korrektheit überprüft werden. Es empfiehlt sich, einen Hashwert mit mindestens 32 Zeichen zu verwenden.

  • redirect_uri muss bei beiden Requests identisch sein und dem für den OAuth Client eingetragenen Redirect-URI-Muster entsprechen.

Mitwirkungspflichten der Kund:innen beim Set-up

Das PORTAL benötigt immer eine Redirect-URI, die kundenseitig angeliefert werden muss.

 

Verwandte Seiten

 

Nur für PEIQ-Mitarbeiter:innen
https://peiq.atlassian.net/wiki/x/IQFQEQ

Impressum