As part of our ongoing efforts to improve security, reliability, and user management, we are transitioning to a new authentification system based on Keycloak. This documentation outlines the key changes required to integrate with the new system, including authentication flows, token management, and configuration updates.

All listed changes must be implemented before mid-September 2025 to ensure continued access and compatibility with our services.

Migration of client scripts

Client scripts will remain fully compatible since the Data Hub API will accept Bearer Tokens from both Identity Server and Keycloak interchangeably.

However, at the time of the transition, all Identity Server clients will be migrated (copied) into Keycloak. This includes the full configuration — meaning the client ID, client secret, scopes, etc.

Things to be changed

Concretely, two things need to be changed:

  1. The token retrieval URL will need to point to Keycloak. If you are hosted on our public EU SaaS, please refer to the Opinum API connection page for the new URL. If you are hosted on another environment, please contact us to receive the new URL.
  2. The target account (note: not all clients use this mechanism)
    1. With Identity Server, the accountId had to be sent in the acr_values parameter using the following format : "acr_values": "accountId:123"
    2. With Keycloak, the accountId must be sent in a parameter called account, at the same level as client_id

Example

Identity:

curl --location 'https://identity.opinum.com/connect/token'\
--header 'Content-Type: application/x-www-form-urlencoded'\
--data-urlencode 'grant_type=password'\
--data-urlencode 'client_id=MyClientId'\
--data-urlencode 'client_secret=MyClientSecret'\
--data-urlencode 'scope=datahub-api'\
--data-urlencode 'username=MyUsername'\
--data-urlencode 'password=MyPassword'\
--data-urlencode 'acr_values=accountId:123'

Keycloak:

curl --location 'https://auth.opinum.com/realms/opinum/protocol/openid-connect/token'\
--header 'Content-Type: application/x-www-form-urlencoded'\
--data-urlencode 'grant_type=password'\
--data-urlencode 'client_id=MyClientId'\
--data-urlencode 'client_secret=MyClientSecret'\
--data-urlencode 'scope=datahub-api'\
--data-urlencode 'username=MyUsername'\
--data-urlencode 'password=MyPassword'\
--data-urlencode 'account=123'

Documented changes

To integrate Keycloak, we had to modify some internal behaviors. The following list aims to outline all known changes. This list is intended to be exhaustive but may evolve in the coming weeks.

Invitation flow

The invitation flow has become a bit more complex with Keycloak.

As a reminder, here is the Identity flow:

  1. An invitation is created
  2. The user receives an email with a link to accept the invitation
  3. The user sets up their Data Hub password
  4. The user is authenticated in Data Hub

With Keycloak, we had to add some steps, so the flow will be:

  1. An invitation is created
  2. The invited user receives an email with a link to accept the invitation
  3. The user is created with a temporary password
  4. The user receives this temporary password by email along with a link to authenticate
  5. The user authenticates using the temporary password
  6. The user must change this temporary password
  7. The user is authenticated in Data Hub

Password restoration

With Identity, users had the ability to change their password directly from a button on the Data Hub profile page (https://datahub.opinum.com/profile).

With Keycloak, the button on the profile page remains accessible, but when the user clicks on it, the following steps will be applied:

  1. A message will be displayed to inform the user that they will be redirected to an external page to change their password.
  2. The user is redirected to Keycloak:
    1. If the user has been authenticated for less than 5 minutes, they can simply enter their new password.
    2. If the user has been authenticated for more than 5 minutes, they will need to enter their current password as well as the new password.
  3. The user is then redirected back to the profile page.

Impersonation

The impersonation flow with Identity Server allowed interrupting impersonation. This would result in returning to Data Hub with the original user's identity.

With Keycloak, interrupting impersonation is equivalent to logging out. This means it will be necessary to re-authenticate.

Masterdata

Identity Server allowed choosing user IDs. This was possible via Masterdata.

With Keycloak, it will no longer be possible to choose this ID.

To keep the system backward compatible, if an ID is specified in Masterdata, this ID will be stored in Keycloak’s BusinessId property.

In most cases, this ID was used to match within an IDP context. When configuring this IDP, it will therefore be important to link it with the BusinessId.

For cases where the client uses the API specifying this custom ID, it will now be necessary to add a lookup that transforms what is now considered the BusinessId into the internal Data Hub ID. More information can be found in the API section below.

API

User Roles

Currently, Data Hub roles are identified by a name and a unique ID in the form of a GUID.

Example:

{
  "id": "4E40D39A-BEBD-4C4A-90DC-67EB1B0D4C9A",
  "name": "Manager"
}

After the transition, since Keycloak does not have the concept of an ID for roles, the ID and the name will have the same value.

Example:

{
  "id": "Manager",
  "name": "Manager"
}

User Claims

Currently, Claims are identified by a claimType, a claimValue, and a unique ID in the form of an integer (int).

Example:

{
  "id": 20890,
  "userId": "59588780-454e-4098-987a-cba7d514337c",
  "claimType": "http://opisense.opinum.com",
  "claimValue": "1"
}

After the transition, since Keycloak does not have a concept of an ID for claims, the key to be used for reading and modifying a claim will be the claimType. The ID will always be set to 0.

Example:

{
  "id": 0,
  "userId": "59588780-454e-4098-987a-cba7d514337c",
  "claimType": "http://opisense.opinum.com",
  "claimValue": "1"
}

User password

A user’s password can no longer be changed via the API.

The endpoint POST /user/password has been replaced by GET /user/updatePasswordLink.

This new endpoint returns a link to Keycloak that initiates the password reset flow.

User Business Keys

It will now be possible to search for users using one of the businessKeys in the filter parameters of the endpoints:

  • /user/users
  • /account/users

These business keys can be based on:

  • Id
  • Username
  • Email
  • BusinessId  

It will be possible to provide multiple values to these filters.

Example with a simple filter:

curl -X 'GET'\
 'https://api-3-qa.opinum.com/user/users?DisplayLevel=Normal&BusinessKeys.Name=BusinessId&BusinessKeys.Values=OLA'\
 -H 'accept: application/json'\
 -H 'Api-Version: 1.7'

Example with multiple values:

curl -X 'GET'\
 'https://api-3-qa.opinum.com/user/users?DisplayLevel=Normal&BusinessKeys.Name=BusinessId&BusinessKeys.Values=OLA&BusinessKeys.Values=GLE'\
 -H 'accept: application/json'\
 -H 'Api-Version: 1.7'