Authentication

Preliminary words

OXOMI differentiates between public and private portals. A private portal requires an authentication of the user before he/she gets to access the data. User maintenance is done via the administrative interface. Approved users then get to log in with a username and password.

If OXOMI is integrated into another system (e.g. an online store, intranet or ERP) twofold user maintenance should generally be avoided. This is why users also get to pass the authentication process via external systems without having to be explicitly registered at and maintained via OXOMI.

An access token, which is generated by the integrating system, facilitates the external authentication.

Please note

Generate the access token directly on your server and fill the parameter in the JavaScript code during the retrieval process to ensure that your portal’s secret key isn’t compromised (intercepted).
To integrate portals that require users to log-in, you’ll need the support of the service provider or the division that oversees your server code.
Generate the access token while the user logs in or while the integration is called up.

If this isn’t possible, you can use the authentication via SAML 2.0 as an alternative.

Authentication via shared-secret

The authentication via shared-secret and access token is relatively simple: We’ll deposit a key (known as shared-secret) in the portal. This key will only be known to the portal and your application. If a user then needs authentication, an access token will be generated via a hash function. This is explained in detail further down this page. OXOMI verifies the access token by performing the same calculations to ensure that the results match.

This method is safe because...
A hash function can’t be reversed. Therefore, a shared-secret can’t be "calculated back".
The shared-secret is only known to OXOMI and your application. Therefore, a valid access token can only originate from these systems.
Since a timestamp is used while generating the access token, a recorded (intercepted) token can not be applied in a malicious way.

Important

Don’t ever share the shared-secret with a third party. And don’t ever openly display the shared-secret on the user interface (don’t show it in a hidden way either → e.g. in HTML code).

The shared-secret is the master key to your portal, which means it provides access to your entire content at all times.

Generating the access token

The hash function MD5 generates the access token. The following parameters are included in the calculation. Should any value be missing, it will be left out:

Parameter	Description
secret	The shared-secret we gave you. This value is required for portals that use a login. This value is not required for public portals.
portal	ID of the portal that is selected.
user	Login name of the user that seeks authentication. This value is required for portals that use a login. This value is not required for public portals.
expires	A UNIX timestamp gets rounded to the whole day. The "seconds-timestamp" gets divided (whole numbers are used) by 86400. 86400 stands for the number of seconds in a day. The conversion into whole days allows a request to remain valid for an entire day. The according calculation in Java code would look like this: `System.currentTimeMillis() / 1000 / 86400` - Keep in mind that this is a whole-numbered division. Therefore, the result is rounded to decimals. The calculated value for a validity that starts today and lasts an entire day is `19829`. The expires value is used to prevent an access token from being intercepted and utilized for an ongoing stretch of time. This has an adjustable tolerance so that an accessToken remains valid even after the date change.
roles	List (separated by commas) that contains the user’s permissions (portal roles). This information can be blank.
uri	If you want the hash value to apply to one specific service only you can add the URI (e.g. /service/json/portal/news) here. Normally, this parameter is left out.
filterLang	If the hash value is supposed to select a certain language to display the portal’s content, a language code (two letter ISO-Code) can be inserted amongst the portal and the user. Normally, this parameter is left out.
filterCountry	If the hash value is supposed to select a certain country for the display of the portal’s content, a country code (two letter ISO-Code) can be inserted amongst the portal and the user. Normally, this parameter is left out.

The following code generates the access token. The + signs indicates a string concatenation.

Example in pseudocode

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

Example with sample values

// Shared secret specific to the portal
secret = 'GEHEIM';
 
// Desired portal
portal = '12345';
 
// Accessing user
user = 'test';
 
// Period of validity
expires = '16646';

// Calculation of the validity for one day:
// = Math.round((new Date()).getTime() / 1000 / 86400);
 
// Role information
roles = '';
 
// Hash calculation
accessToken = md5('GEHEIM' + md5('GEHEIM' + '12345' + 'test' + '16646'));

Our access token calculator helps you with generating your customized token: Access-Token Calculator

The access token is also used to authenticate links pointing to OXOMI content. To learn more about this, head to the section Deeplinks.

Back to overview