Names

The Collaboratory 1 authentication service is implemented by a MITREid server.

The Collaboratory 2 authentication service is implemented by a Keycloak server.

We refer to these two names below.

Requirements

Before proceeding, you should read the following documentation about OIDC clients in Collaboratory 2:

1. how to register an OIDC client
2. how to authenticate with your OIDC client.

OIDC endpoints

In the code of your app, you have to replace MITREid URLs by the equivalent Keycloak URLs.

MITREid endpoints

Keycloak endpoints

Identifying your app's existing users

Your user's access token in Keycloak provides your app with more information than it did in MITREid.

MITREid

{
  "exp": 1602247693,
 "sub": "305862",
  "aud": [
    "portal-client"
  ],
  "iss": "https://services.humanbrainproject.eu/oidc/",
  "jti": "c10621ea-7999-4975-b412-1cb43e156fb9",
  "iat": 1602074893,
  "hbp_key": "958351d7c1f26301d605b550a066b93e38c931de"
}

Keycloak

{
  "exp": 1602708758,
  "aud": [
    "team",
    "group"
  ],
"sub": "fa2db206-3eb4-403c-894a-810ebaba98e1",
  "typ": "Bearer",
  "azp": "jupyterhub",
  "scope": "profile clb.wiki.write email openid clb.wiki.read",
  "email_verified": true,
  "name": "Demo Account",
  "mitreid-sub": "302862",
"preferred_username": "demoaccount",
  "given_name": "Demo",
  "family_name": "Account",
  "email": "demo.account@epfl.ch"
}

The MITREid access token provides a "sub" field which contains the userid. The access token does not provide other identification. It's therefore likely that applications used this userid instead of the user's username.

In Collaboratory 2,  We recommand you to use the preferred_username field (which is the username) to identify your users for every new users in your system. The preferred_username is used by us as unique identifier in The Collaboratory, it's really friendly to use it and interact easily with our IDM Api. We are guaranting its unicity.

You can also use the sub provided by keycloak which is the OIDC/OAuth2 standard unique identifier for a user and might be consider as the good choice. If in addition you store the username associate to the sub you will still be able to use easily our IDM Api, if not you will maybe need to perform one more request to get the User object from your sub in the IDM Api

In order to map Collaboratory 1 userids which you might have stored, you can use the mitreid-sub field, which is the Collaboratory 1 userid for the user with the same username / email address at the time of the registration of the Collaboratory 2 account. In the exceptional cases when the access token does not provide a "mitreid-sub" value, you can consider that the user doesn't have an account in Collaboratory 1. After shutdown of the collaboratory one, new users not havening a Collaboratory 1 account will be the norm obviously because Collaboratory 1 won't exist anymore. At this moment we are recommanding you to still use `mitreid-sub` when available and to consider using `preferred_username` or the new keycloak `sub` (not really user friendly) for your new users.

 

Equivalence of user info between Collaboratory 1 and 2

You can get more information about your user at the endpoint:

https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo

All information about userinfo and the required scope is available in the documentation:

how to authenticate with your OIDC client

Accreditation