SSO Anbindung

Die Anbindung einer bestehenden SSO (Single Sign On) an Ihre Publikation beginnt mit der Einrichtung eines Identity Providers im oliwol Publisher Tool.

Erstellung eines Identity Providers

Authentifizierung

Ein Identity Provider verlangt immer nach einer Authentifizierungs-URL, deren Response ein JSON-Objekt zurückliefert. Im GET-Request wird als Parameter die Produkt-ID [pId] als Slug mitgeliefert, damit Sie Anfragen aus verschiedenen Publikationen unterscheiden können. Ein beispielhafter Response könnte wie folgt aussehen:

Sie können zwischen zwei Authentifizierungs-Typen wählen: Session und Token. Bei der Verwendung der Token-Variante müssen Sie in einem zusätzlichen Feld den Key innerhalb des JSON-Response angeben, der den Token als Wert enthält. Der Token wird im localStorage abgelegt und bei jedem zukünftigen Request an die Authentifizierungs-URL im Header übergeben: "Authorization": "Bearer [token]".

Key-Value-Pairs

Eine erfolgreiche Authentifizierung kommt erst dann zustande, wenn die Key-Value-Pairs aus dem Feld Auth success status mit dem Response übereinstimmen. Dies wird anhand des nachfolgenden Beispiels erklärt. Ihre Authentifizierungs-URL liefert folgenden Response:

Im Feld Auth success status definieren Sie eine erfolgreiche Authentifizierung mit dem Key-Value-Pair: auth: true

Authentifizierung mit Key-Value-Pairs

Liefert der Key auth einen anderen Wert als true zurück, findet keine Authentifizierung statt.

Sie haben die Möglichkeit eine Authentifizierung von mehreren Key-Value-Pairs abhängig zu machen. Beispielsweise wollen Sie neben der Authentifizierung auch prüfen, ob ein/e Nutzer:in auch seine/ihre Email-Adresse bestätigt hat.

Multidimensionale Objekte

Um auf Keys innerhalb von multidimensionalen Objekten zugreifen zu können, nutzen Sie Punkte (.) als Trenner zwischen den Objekt-Ebenen.

Key-Value-Pairs in multidimensionalen Objekten

Sowohl auth: true als auch optin: true stimmen mit dem Response überein - die Authentifizierung ist erfolgreich.

Nun wollen Sie auch auf die im Beispiel-Response angegebenen abonnierten Produkte prüfen. Wenn ein Key als Wert ein Objekt oder Array enthält, wird geprüft, ob der Wert innerhalb des Objekts oder Arrays vorkommt.

Key-Value-Pairs in multidimensionalen Objekten

Die Authentifizierung ist erfolgreich, da es innerhalb von products einen Eintrag mit expired: false gibt.

Wildcard

Um einen Wert innerhalb einer Zeichenkette zu finden, können Wildcards (*) vor und/oder nach dem Wert verwendet werden (z.B.: *Premium*).

Wildcard für Key-Value-Pairs nutzen

Auch hier findet eine erfolgreiche Authentifizierung statt, da "Premium" innerhalb des Eintrags "Games Premium" enthalten ist.

Aktivierung der SSO

Da Identity Provider nicht innerhalb von Publikationen angelegt werden, haben Sie die Möglichkeit, eine konfigurierte SSO mehrfach zu verwenden. Änderungen an der SSO, wirken sich demnach auch auf alle Publikationen aus, die mit dem Identity Provider verbunden sind.

Innerhalb einer Publikation können Sie im Bereich Authentication unter Custom SSO Ihren angelegten Identity Provider auswählen.

Aktivierung einer Custom SSO

Username

Der Username ist ein Pflichtfeld, da dieser im Profil von Nutzer:innen ausgegeben wird. Hierbei ist es unerheblich, ob es sich um einen echten Namen, eine E-Mail-Adresse oder ein Pseudonym handelt.

Anzeige des Username

Damit der Name bzw. die E-Mail-Adresse im Profil eines Nutzers dargestellt werden kann, muss eine Übergabe im JSON-Response stattfinden.

x
Auswahl des Username im JSON-Response

In diesem Beispiel wird im Profil die E-Mail-Adresse als m**i@muster.example dargestellt.

Synchronisation der Spieldaten

Die Spieldaten (Statistiken, letzte Spielergebnisse, etc.) eines Nutzers werden im localStorage des Browsers abgelegt. Dementsprechend findet nur eine temporäre Speicherung der Daten statt. Wenn Nutzer:innen verschiedene Browser bzw. Devices nutzen oder Browserdaten löschen, werden die Daten nicht synchronisiert.

Um Spieldaten persistent zu speichern haben Sie die Möglichkeit eine Synchronisations-URL zu hinterlegen.

Synchronisations-URL

Wie bei der Authentifizierungs-URL wird im Request die Produkt-ID [pId] mitgegeben, damit Sie die Spieldaten auch der korrekten Publikation zuordnen können. Zusätzlich wird im POST-Request der Key storage mitgeliefert, der ein JSON-Objekt mit den Spieldaten des Nutzers als String enthält. Dieser String muss bei der Rückgabe exakt in der selben Form zurückgeliefert werden. Eine Verarbeitung des Response findet nicht statt.

Entweder erstellen Sie in der User-Tabelle für jedes Produkt [pId] eine eigene Spalte. Bspw. sudoku_storage. Oder Sie speichern die Daten in einem JSON-Feld storage im folgendem Format:

Letztere Methode hat den Vorteil, dass Sie die User-Tabelle bei neuen Publikationen nicht erweitern müssen.

Rückgabe der Spieldaten

Die Rückgabe der Spieldaten erfolgt über die Authentifizierungs-URL, die beim Aufruf einer Publikation angefragt wird. Die Daten müssen im JSON-Response übergeben werden:

Sobald eine Synchronisations-URL im Identity Provider hinterlegt wurde, kann innerhalb einer Publikation der Key im JSON-Response angegeben werden, der die Spieldaten enthält.

Key für Spieldaten im JSON-Response der Authentifizierungs-URL

Bei Aufruf der Publikation, werden nach erfolgreicher Authentifizierung die Spieldaten validiert und im localStorage abgelegt.

Login

Beim Anlegen eines Identity Providers müssen Sie die URL zum Login Ihrer SSO hinterlegen.

Login URL

Zusätzlich muss ein Parameter angegeben werden, der an die Login-URL angehängt wird und die Landing-Page für eine erfolgreiche Anmeldung enthält, an den Sie den/die Nutzer:in weiterleiten können.

Redirect Parameter für den erfolgreichen Login

Wenn der/die Nutzer:in sich einloggt, landet er/sie auf folgender Seite:

Login über iframe

Alternativ können Sie auch die iframe-Variante für den Login nutzen.

Login via iframe

In diesem Fall öffnet sich beim Login ein Layer mit iframe, das die Login-URL lädt. Sie können den Layer in der Breite anpassen. Die Breite wird in Pixeln angegeben.

Die Applikation lauscht zusätzlich auf ein postMessage-Event, das eine Höhe sowie eine erfolgreiche Authentifizierung entgegennimmt und verarbeitet. Die Mindesthöhe des iframes wird zunächst auf 416 Pixel gesetzt. Sie können diese wie folgt anpassen:

In diesem Fall muss das Feld Iframe height key den Wert "height" erhalten, damit die Applikation den Key aus dem postMessage-Event auslesen kann. Das iframe wird daraufhin in der Höhe auf den von Ihnen übergebenen Wert angepasst.

Um der Publikation eine erfolgreiche Authentifizierung mitzuteilen, müssen Sie im Feld Iframe success status ein Key-Value-Pair hinterlegen, auf das gelauscht wird.

Login über das postMessage-Event

Das postMessage-Event sollte folgenden Payload enthalten, um einen Reload der Publikation auszulösen.

Nachdem Reload ist der/die Nutzer:in in der Applikation eingeloggt.

Logout

Wenn Sie Ihren Nutzer:innen die Möglichkeit geben möchten, sich innerhalb der Publikation auszuloggen, steht Ihnen das Feld Logout URL zu Verfügung. Im Menü erscheint ein Link, der einen asynchronen GET-Request auslöst.

Logout

Der Response wird nicht verarbeitet. Nachdem der Request einen 200er Status-Code liefert, wird der/die Nutzer:in aus der Publikation ausgeloggt.

Profil

Eingeloggte Nutzer:innen haben Zugriff auf ein eigenes Profil. Sie haben die Möglichkeit Ihren Nutzer:innen innerhalb ihres Profils Service-Links zu hinterlegen, wie beispielsweise Links zum bearbeiten der Profildaten oder um das Profil zu löschen.

Profil