Authentifizierung

OXOMI unterscheidet zwischen öffentlichen und geschlossenen Portalen. Bei geschlossenen Portalen muss ein Benutzer authentifiziert werden, bevor er Zugriff auf die Daten erhält. Diese Benutzer können über die Administrationsoberfläche gepflegt werden und sich dann mit Benutzernamen und Passwort anmelden.

Wird OXOMI in ein anderes System, wie z.B. einen Onlineshop, ein Intranet oder ERP integriert, soll eine doppelte Benutzerpflege aber meist vermieden werden. Deshalb können Benutzer auch durch externe Systeme authentifiziert werden, ohne dass diese in OXOMI explizit angelegt und gepflegt werden müssen.

Für die externe Authentifizierung kann ein im integrierenden System generierter Access-Token eingesetzt werden. Dies kann ein universeller Access-Token oder ein abgegrenzter API-Token sein.

Im Portal wird von uns das sogenannte Shared-Secret als Schlüssel hinterlegt. Dieser Schlüssel ist ausschließlich dem Portal und Ihrer Anwendung bekannt. Soll ein Benutzer nun authentifiziert werden, so wird durch eine Hash-Funktion ein Access-Token berechnet. Dies wird weiter unten im Detail beschrieben. OXOMI verifiziert den Access-Token, indem es die gleiche Berechnung ausführt und prüft, ob es zum selben Ergebnis kommt.

Der Access-Token wird auch genutzt, um Links direkt zu OXOMI zu authentifizieren. Details hierzu finden Sie im Kapitel Deeplinks.

• Eine Hash-Funktion ist per Definition nicht umkehrbar, das Shared-Secret kann also nicht „zurückgerechnet“ werden.
• Da das Shared-Secret nur OXOMI und Ihrer Anwendung bekannt sind, kann ein valider Access-Token nur von diesen Systemen stammen.
• Da ein Zeitstempel zur Berechnung des Access-Token herangezogen wird, kann auch ein aufgezeichneter (abgefangener) Token nur für einen kurzen Zeitraum nachteilig verwendet werden.

Zur Berechnung des Access-Tokens wird die Hash-Funktion MD5 verwendet. Die folgenden Parameter fließen in die Berechnung mit ein. Ist ein Wert nicht vorhanden, so wird dieser weggelassen:

Der folgende Code berechnet den Access-Token. Die + Zeichen sind hier als String-Verkettung zu verstehen.

Beispiel in Pseudocode

accessToken = md5(secret + md5(secret + portal + user + expires + roles))

Eine andere Möglichkeit zur Authentifizierung ist mittels eines generierten API-Tokens. Die Nutzung eines API-Tokens ist sicherer als die Nutzung des SharedSecrets, da verschiedene API-Token angelegt werden können und auch wieder gelöscht werden können. So können für verschieden Anwendungszwecke verschiedene API-Token verwendet werden. Ein API-Token kann in den Portal-Einstellungen angelegt werden. Zu jedem API-Token gehört eine ID und ein eigenes Secret, das in der Berechnung genutzt wird.

Zur Berechnung des Access-Tokens wir die im Portal hinterlegte Hash-Funktion verwendet. Im Normalfall und in den weiteren Beispielen in diesem Artikel ist dies die MD5 Funktion. Die folgenden Parameter fließen in die Berechnung mit ein. Ist ein Wert nicht vorhanden, so wird dieser weggelassen:

Der folgende Code berechnet den Access-Token. Die + Zeichen sind hier als String-Verkettung zu verstehen.

Beispiel in Pseudocode

accessToken = md5(secret + md5(tokenSecret + tokenId + portal + user + expires + roles))

Um die für den authentifizierten Benutzer verfügbaren Kontaktdaten anzureichern, kann die BUZZ Capability enhanceUserData genutzt werden. Diese Daten werden anschließend beispielsweise im Paperclip- oder Rückfrage-Dialog zur Vorbefüllung der Kontaktdaten des aktuellen Nutzers genutzt. Zudem bietet sie die Möglichkeit, auch Integrationen, die lediglich über einen Hash authentifiziert sind und bei denen keine automatische Anlage von Portal-Benutzern im Portal aktiv ist, mit Kontaktdaten zu versorgen.

In der empfangenen Nachricht stehen die folgenden Informationen:

Als Ergebnis wird ein Objekt mit denselben Feldern erwartet. Es müssen nicht alle Felder angegeben werden und die Werte können dabei verändert werden, um einzelne Felder zu überschreiben oder zu ergänzen.

Beispiel:

shop.addCapability('enhanceUserData', function (message) {
    const user = message.payload();

    user.firstname = 'Max';
    user.lastname = 'Mustermann';
    user.email = 'max@musterfirma.de';
    user.company = 'Musterfirma';
    user.department = 'Musterabteilung';

    message.reply(user);
});

Interaktives Code-Beispiel