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.
Sollte das nicht möglich sein, kann auf die Authentifizierung mittels SAML 2.0 zurückgegriffen werden.
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. |
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.
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
Der berechnete Wert für eine ab heute beginnende eintägige Gültigkeit ist
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.
accessToken = md5(secret + md5(secret + portal + user + expires + roles))
// 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.