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. Dies kann ein universeller Access-Token oder ein abgegrenzter API-Token sein.

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

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.

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 nur für einen kurzen Zeitraum nachteilig verwendet werden.
Hinweis

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. Unser Support wird Sie nie nach Ihrem Shared-Secret fragen.

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 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:

Parameter Beschreibung
portal Die ID des Portals, welches angesteuert werden soll.
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.

user

Der Loginname des Benutzers, der authentifiziert werden soll.

Dieser Wert muss bei Login-geschützten Portalen vorhanden sein. 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 19327.

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 Access-Token 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.
filterLanguage Soll der Hash-Wert eine bestimmte Sprache für die Portalinhalte festlegen, kann zwischen Portal und User der Code der Sprache (als 2-buchstabiger 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-buchstabiger 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))
Access-Token Rechner
Eindeutige Bezeichnung des gewünschten Portals, welche im Backend eingesehen werden kann.
Portalspezifischer Geheimschlüssel, der Ihnen von scireum mitgeteilt wurde.
Benutzername des zu authentifizierenden Benutzers.
Ein UNIX-Timestamp auf ganze Tage gerundet. Wird verwendet, um zu verhindern, dass ein Access-Token abgefangen und danach endlos lange weiterverwendet werden kann.
Komma-getrennte Liste mit Portalrollen des Benutzers.
Berechnen
Authentifizierung mittels API-Token

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.

Hinweis

Geben Sie das API-Token-Secret niemals an Dritte weiter. Zeigen Sie das API-Token-Secret niemals in der Oberfläche oder verdeckt (z.B. in HTML-Code) an. Unser Support wird Sie nie nach Ihrem API-Token-Secret fragen.

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

Bitte beachten Sie, dass die Authentifizierung über API-Token noch nicht bei allen Integrationen möglich ist.

Berechnung des API-Tokens

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:

Parameter Beschreibung
portal Die ID des Portals, welches angesteuert werden soll.
tokenId

Die ID des API-Tokens

Dieser Wert kann in den Portal-Einstellungen eingesehen werden.

tokenSecret

Das Shared-Secret des API-Tokens

Dieser Wert kann in den Portal-Einstellungen eingesehen werden.

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.

user

Der Loginname des Benutzers, der authentifiziert werden soll.

Dieser Wert muss bei Login-geschützten Portalen vorhanden sein. 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 19327.

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 Access-Token auch über den Datumswechsel hinaus gültig bleibt.

roles

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

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))
API-Token Rechner
Eindeutige Bezeichnung des gewünschten Portals, welche im Backend eingesehen werden kann.
Eindeutige Bezeichnung des API-Tokens, welche im Backend eingesehen werden kann.
Geheimschlüssel des API-Tokens, welcher im Backend eingesehen werden kann.
Portalspezifischer Geheimschlüssel, der Ihnen von scireum mitgeteilt wurde.
Benutzername des zu authentifizierenden Benutzers.
Ein UNIX-Timestamp auf ganze Tage gerundet. Wird verwendet, um zu verhindern, dass ein Access-Token abgefangen und danach endlos lange weiterverwendet werden kann.
Komma-getrennte Liste mit Portalrollen des Benutzers.
Berechnen
See also
Enthält Informationen über die von OXOMI unterstützten Browser Versionen.