OAuth-Login über PORTAL

Funktionalitäten des OAuth-Logins über das PORTAL:

• Authentifizierung in einem externen System über das PORTAL

• Abgleich der 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:

• Textomatic-Login über PORTAL-OAuth

• E-Paper-Login über PORTAL-OAuth

• Login im PRINT PPS über PORTAL

Workflow

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 Standart. 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 API Zugänge verwalten selbst generiert werden. Falls diese Funktion nicht freigeschalten ist, muss der Zugang von PEIQ erstellt werden. In diesem Fall bitte an das PEIQ Support Team wenden.

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

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 seinem 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 Popup bzw. weiteren Fenster

   # Login Form
   https://example.com/oauth/v2/auth
     ?client_id=<client id>
     &state=<unique NONCE value>
     &response_type=code
     &redirect_uri=https://example-redirect-uri.com/returnpath

2. Auswerten des Authorization Codes

   # Der Return Path wird bei erfolgtem Login mit dem Code und State als
   # Query Parameter aufgerufen
   https://example-redirect-uri.com/returnpath?code=<authcode>&state=<unique NONCE value>

3. Access Token mit Hilfe des Authorization Codes erstellen

   https://example.com/oauth/v2/token
     ?client_id=<client id>
     &client_secret=<client secret>
     &grant_type=authorization_code
     &redirect_uri=https://example-redirect-uri.com/returnpath
     &code=<authorization code>

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 des Kunden beim Set-up

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

Verwandte Seiten