Authentifizierung


Vorbemerkungen

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.

 Hinweis

  • Berechnen Sie diesen Access-Token direkt auf Ihrem Server und füllen Sie den Parameter im JavaScript per Aufruf, damit der Geheimschlüssel Ihres Portals nicht abgefangen werden kann.
  • Für die Integration Login-geschützter Portale benötigen Sie also die Unterstützung des Dienstleisters oder der Abteilung die Ihren Servercode betreut.
  • Bei mehreren Portalbenutzern muss der Access-Token für jeden individuell berechnet werden.
  • Berechnen Sie den Access-Token entweder beim Login des Nutzers oder in dem Moment des Aufrufs der Integration.

Sollte das nicht möglich sein, kann auf die Authentifizierung mittels SAML 2.0 zurückgegriffen werden.

Authentifizierung mittels Shared-Secret

Die Authentifizierung mittels einem Shared-Secret und Access-Token ist relativ einfach: 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.

Dieses Verfahren ist sicher, weil...
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 nicht nachteilig verwendet werden.

 Wichtig

Geben Sie das Shared-Secret niemals an Dritte weiter. Zeigen Sie das Shared-Secret niemals in der Oberfläche oder verdeckt (z.B. in HTML-Code) an.

Das Shared-Secret ist der Generalschlüssel zu Ihrem Portal, womit zu jeder Zeit Zugriff auf sämtliche Inhalte erfolgen kann.

Berechnung des Access-Tokens

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

Parameter Beschreibung
secret

Das Shared-Secret, welches Sie von uns mitgeteilt bekommen.

Dieser Wert muss bei Login-geschützten Portalen vorhanden sein. Bei öffentlichen Portalen ist dieser Wert nicht notwendig.

portal Die ID des Portals, welches angesteuert werden soll.
user

Der Loginname des Benutzers, der authentifiziert werden soll.

Dieser Wert sollte bei Login-geschützten Portalen vorhanden sein, rein technisch kann auch ein Access-Token für den Benutzer '' berechnet werden. Bei öffentlichen Portalen ist dieser Wert nicht notwendig.

expires

Ein UNIX-Timestamp auf ganze Tage gerundet.

Der Timestamp in Sekunden wird ganzzahlig durch 86400 (Anzahl der Sekunden pro Tag) dividiert. Das Umrechnen auf ganze Tage sorgt dafür, dass eine Anfrage effektiv einen Tag gültig bleibt.

Die entsprechende Berechnung würde in Java-Code folgendermaßen aussehen System.currentTimeMillis() / 1000 / 86400 - Beachten Sie dass dies eine ganzzahlige Division ist, das Ergebnis entspricht also dem abgerundeten Wert Division mit Dezimalzahlen.

Der berechnete Wert für eine ab heute beginnende eintägige Gültigkeit ist 20069.

Der expires Wert wird verwendet, um zu verhindern, dass ein Access-Token abgefangen und danach endlos lange weiterverwendet werden kann. Das weist eine einstellbare Toleranz auf, so dass ein accessToken auch über den Datumswechsel hinaus gültig bleibt.

roles

Komma-getrennte Liste von Berechtigungen (Portalrollen) des Benutzers. Diese Angabe kann leer sein.

uri Soll der Hash-Wert nicht für alle Portal-Aufrufe gelten, sondern nur für einen bestimmten Service, kann man an dieser Stelle die URI (z.b. /service/json/portal/news) einfügen. Im Normalfall wird dieser Parameter weggelassen.
filterLang Soll der Hash-Wert eine bestimmte Sprache für die Portalinhalte festlegen, kann zwischen Portal und User der Code der Sprache (als 2-buchstabigen  ISO-Code) einfügt werden. Im Normalfall wird dieser Parameter weggelassen.
filterCountry Soll der Hash-Wert ein bestimmtes Land für die Portalinhalte festlegen, kann zwischen Portal und User der Code des Landes (als 2-buchstabigen  ISO-Code) einfügt werden. Im Normalfall wird dieser Parameter 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))

Beispiel mit Beispielwerten

// Portalspezifischer Geheimschlüssel
secret = 'GEHEIM';
 
// Gewünschtes Portal
portal = '12345';
 
// Zugreifender Benutzer
user = 'test';
 
// Gültigkeitszeitraum
expires = '16646';

// Gültigkeitsberechnung für einen Tag:
// = Math.round((new Date()).getTime() / 1000 / 86400);
 
// Rolleninformation
roles = '';
 
// Hash-Berechnung
accessToken = md5('GEHEIM' + md5('GEHEIM' + '12345' + 'test' + '16646'));

Nutzen Sie als Hilfsmittel unseren Access-Token Rechner, um sich Ihren individuellen Token zu berechnen: Access-Token Rechner

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