Identity in the Collaboratory 2.0 is provided by the identity and authentication management (IAM) service at https://iam.ebrains.eu. The IAM server provides a single-sign-on (SSO) across all integrated tools. It also provides a mechanism for services to connect to each other on behalf of a user. This document provides an overview of the protocol used, Collaboratory IAM service, EBRAINS user directory and instructions on using the IAM service to set up an application or run a service. The objective of this document is to help the reader setup a secure service within the HBP ecosystem.
This document is technical and aimed at developers setting up a service, or technical project managers planning to do so. Background knowledge of fundamental issues on security and software development are expected from the audience. It is still necessary for the developers to follow up on the main concepts of authentication, authorization and OIDC in order to build a secure application.
Introduction to OIDC
Terminology and Background Material
First, authentication and authorization are two different concepts. Authentication is the process of verifying your identity. Authorization is the act of granting or denying the right of a user to complete an action. Here is an example: if you show up to a secure building and you show your identity card to a guard, the guard is authenticating you. Next, when the guard looks up your name in a list of guests, he is checking whether you have authorization to enter the builing.
In the HBP, we use the OpenID Connect (OIDC) protocol for authentication, and the OAuth 2.0 framework for authorization. OIDC is built on top of OAuth to provide an identity layer. OIDC and OAuth 2.0 are specifications of a protocol. A protocol is like a code: if I say “Palm tree”, let me in, if I say “Coconut”, turn on the lights. In order to use a protocol, you need an implementation: a program that takes care of reacting to each request based on the protocol. We use KeyCloak as our IAM server.
As mentioned above, KeyCloak is a program that uses OIDC to identify you and do authorization. Sometimes, like when you go to the theatre, you can be authorized to enter without proving your identity, simply by presenting a ticket. OAuth 2.0 allows a service (a special type of program) to obtain a ticket on your behalf from our IAM server. This ticket then allows the service to connect to other services on your behalf. These tickets usually contain information about your identity as well as some hints about authorization.
You can find the detailed terminology for the OIDC protocol here, and I have summarised and explained a few key terms here:
OpenID Provider (OP): This is the service that tracks user identities and implements the OIDC protocol. In our case, it can: https://iam.ebrains.eu/auth/realms/hbp.
Relying Party (RP): This is an app that uses the OP to authenticate or authorize a user. Examples in our case are the Lab at https://lab.ebrains.eu, and the Drive at https://drive.ebrains.eu.
Service Provider (SP): This is not strictly speaking a term in the OAuth or OIDC or OAuth vocabulary, but from another procotol called SAML. It is SAML’s equivalent to the relying party described above.
Identity Provider (IdP): An identity provider is once again not from the OIDC vocabulary, but from SAML. It is the equivalent of the OIDC Provider.
Client: A client is app that can connect to a protected resource on behalf of the user. This is true of any RP. A client must be registered on the OP. This means that, if you want to create an app for users, you must register a client with IAM.
Scopes: Scopes are used to authorize a client to access certain resources on behalf of the user. If a user Alice connects to an RP such as the Lab, and she wants to access files from the drive, she must agree to let the client (Lab) to access files on the drive by granting the scope. This happens when she authenticates with the OP, our IAM server. The scopes Alice grants are stored by IAM and passed in the token (like a ticket) which Lab receives. The Lab can then use this token to connect to Drive and download Alice’s files.
token: A string that has special meaning for authorization or identification.
Claims: These are data that are embedded in the token, providing identify or authorization information, for example: email.
Authorization, Roles and HBP Units, Groups, and Teams
This section outlines the HBP structure, and the workflow we suggest for validating identity and managing authorization. We provide an OIDC provider in our IAM service. We manage user accounts, and users which have an official capacity in HBP, partnering projects and the governance are placed in units according to their role in the project. Users also are placed within an institution, which is part of a country. We suggest that service providers create groups and assign them to units, other groups or individual users to manage permissions within their app.
Users should sign up with their institutional email which is regularly validated. They are then placed in a unit corresponding to the institution they belong to as well as the country it belongs in. This is all information about the user’s identity. We also provide the possibility to manage groups.
These groups can be used to assign a role to a user or unit. You can give Alice and all Work Package 3 members (/all/projects/hbp/consortium/SGA3/WP3/) a role called my-‘brain-team-viewer’. These units groups are available to services that have created and OIDC client. They can be used to manage permissions within your service.
Units: the Organistational Structure
Units represent the organisation structure of HBP, EBRAINS and partners. SGA2 accreditations are imported from the Collaboratory 1. For SGA3, accreditations are requested by asking to join a task. The task leader and work package managers can approve the user’s request. By accepting the request, the responsible person is granting an accreditation. The accreditor is responsible for removing the person from the unit upon departure.
The structure of units is the following:
Users' units under /all/projects/hbp/consortium/SGA3 are validated by the Work Package managers and task leaders. Institutions are validated by veryfing the users' access to their official email.
Groups: User managed
Users can request a special permission to be able to create groups. User managed groups can be searched for in the identity app. The list of groups a user belongs to can be found by querying the userinfo endpoint with the user’s access token.
Teams
Teams are special groups associated with a Collab. A team has Each collab has three gro
TODO: Can client holders create client roles?
For Service Providers
If you wish to create a service or an application that integrates into the Collaboratory, this section explains how to proceed.
Registering a Client
To register a client, follow the instructions here.
ID, Access & Refresh Tokens
OIDC Endpoints
Userinfo
Connecting to a Protected Backend Service
For Users
Scopes
The Collaboratory 2.0’s IAM server tracks the authorization that a user has granted to services. These are the OAuth scopes. It will be explained in more details below. The IAM server also tracks information about the users which can be relevant for authorization within a service.
Community App in Collabs
Community apps are apps developed by... the community. In order to make them available to Collab editors, app needs to be registered in a space called "Apps Catalogue". Once the app is available to editors, adding such an app to a Collab is as simple as creating a new page in the Collaboratory.wiki.
Register App in App Catalogue
Apps catalogue is available at: https://wiki.ebrains.eu/bin/view/Apps/
App registration is available to members of this group: https://wiki.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam--service-providers
To register an app, click on "create App", if button does not appear, you are probably not a member of the group previously mentioned. You can send a request to become a member and them have permissions to create apps.
Then create a new space for your app using the "Community Apps" type.
On the next step, just fill the form to make your app available to collab editors. Note that only users registered in the "maintainers" field will be able to edit this form. Don't forget to add yourself. When done, click on "Save and View" button, it displays a summary of information you have just filled. Your app is now available to be used in the Collaboratory.wiki.
Add Logo (optional)
Some of users would like to add a logo to their app, logo is visible when browsing the catalogue only. To do so, user has to add a PNG file attachment with filename equal to "logo.png" in the attachment tab on the summary page displayed after the "Save & View" action.