SSO Anbindung ​

Das oliwol Publisher Tool bietet Ihnen die Möglichkeit, ohne weiteren Entwicklungsaufwand Ihre SSO anzubinden. Spieldaten und Statistiken Ihrer Nutzer:innen können so persistent gespeichert werden. Darüber hinaus ermöglicht die SSO-Anbindung Ihnen erweiterte Spielfunktionen oder Vorteile nur für Abonnent:innen freizugeben.

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

Authentifizierung ​

Sie können zwischen drei Authentifizierungs-Typen wählen: Session, JWT und Token. Die Methoden Session und Token erwarten einen 2XX Status Code für eine erfolgreiche Authentifizierung. JWT validiert mit Hilfe des Public Keys den im Cookie hinterlegten Token. Optional kann der Payload mit der Eingabe von Key-Value-Pairs auf spezielle Werte überprüft werden, um eine erfolgreiche Authentifizierung zu definieren.

Session ​

Eine Authentifizierung über eine Session benötigt die Angabe einer URL, die via XMLHttpRequest (GET) angefragt wird. Sobald die Anfrage einen 2XX Status Code zurückliefert, findet eine Authentifizierung statt.

JWT ​

Bei Verwendung der JWT-Methode hinterlegen Sie den Namen des Cookies, der das Token enthält. Das Cookie darf kein httpOnly-Flag enthalten, da die Anwendung den Wert sonst nicht auslesen kann. Zusätzlich muss der Public Key des JWT hinterlegt werden, um den Token zu validieren.

Token ​

Bei der Token-Variante geben Sie sowohl eine URL als auch den Namen des Cookies an, das den Token enthält. Ein XMLHttpRequest (GET) stellt zusammen mit dem Authorisierungs-Token eine Anfrage an die hinterlegte URL. Wird diese mit einem 2XX Status Code beantwortet, findet eine Authentifizierung statt.

Key-Value-Pairs ​

Mit Hilfe von Key-Value-Pairs haben Sie die Möglichkeit eine Authentifizierung zu definieren. Ein 2XX Status Code ist bei den Methoden Session und Token jedoch immer erforderlich. Key-Value-Pairs werden auf Übereinstimmungen mit dem Payload des Response überprüft. Bei den Methoden Session und Token wird das JSON-Objekt des Response ausgelesen, bei JWT der Payload des Token. Dies wird anhand des nachfolgenden Beispiels erklärt.

Ihre Authentifizierungs-URL liefert folgenden Response:

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

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 Nutzer:innen ihre Email-Adresse bestätigt haben.

Multidimensionale Objekte ​

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

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.

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*).

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.

Synchronisation ​

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.

Sobald Sie Ihre SSO an das oliwol Publisher Tool anbinden, werden bei einer Authentifizierung die Daten persistent gespeichert. Bei der ersten Authentifizierung wird im System ein Datensatz pro Nutzer:in angelegt. Unter dem Menüpunkt Spieler:innen finden Sie alle Nutzer:innen aus Ihrem System, die eine oder mehrere Publikationen verwenden.

Payload ​

Um Daten von Nutzer:innen im oliwol Publisher Tool korrekt zuzuordnen sowie im Profil darzustellen, können Sie Werte aus dem Payload extrahieren. Bei den Methoden Session und Token wird jeweils auf den Response (JSON) zugegriffen. Bei JWT wird der Payload des Token ausgelesen. Verschachtelte Objekte im Payload trennen Sie mit einem Punkt (z. B.: data.user.id).

User ID

Bei der User-ID handelt es sich um eine von Ihnen festgelegte, eindeutige ID, worüber Sie Nutzer:innen identifizieren. Die Spieldaten und Statistiken werden der ID zugeordnet. Die User-ID ist demnach ein Pflichtfeld. Die maximale Länge beträgt 255 Zeichen.

Für den obigen Response können Sie die User-ID über den Key user.id extrahieren.

Username / E-Mail

Der Username wird im Profil der Spieler:innen angezeigt und kann für Rankings genutzt werden. Hierbei ist es unerheblich, ob es sich um einen echten Namen, eine E-Mail-Adresse oder ein Pseudonym handelt. Im oliwol Publisher Tool können Sie im Bereich Spieler:innen nach einem Namen bzw. einer E-Mail-Adresse suchen. Wenn Sie keinen Key für Username und E-Mail angeben, wird im Profil der Nutzer:innen Anonym ausgegeben.

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

In diesem Beispiel wird im Profil der Name M. Muster ausgegeben.

Login ​

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

Zusätzlich muss der Name des Parameters angegeben werden, den Sie auf Ihrer Login-URL auslesen können. Der Parameter enthält als Wert die URL, auf die Sie die Spieler:innen nach erfolgreichem Login zurückleiten.

Nach erfolgreichem Login landen Nutzende in diesem Beispiel auf der URL, die im Parameter source angegeben ist:

Login über iframe ​

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

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 hört 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 gehört wird.

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.

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.