Tutorial
Identity in the Collaboratory 2.0 is provided by the identity and access management (IAM) service at https://iam.ebrains.eu. The IAM server provides a single sign-on (SSO) solution across all EBRAINS services. It also provides a mechanism for services to connect to each other on behalf of an EBRAINS user. This document provides an overview of the Collaboratory IAM service, the protocol used, 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 EBRAINS 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 concepts in 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 the guards, the guards are authenticating you. Next, when the guards look up your name in a list of guests, they are checking whether you have authorization to enter the building.
In EBRAINS, 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.
KeyCloak is a program that uses OIDC to identify users and to manage 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. In OIDC, these tickets usually contain information about the user's identity as well as some hints about authorization.
You can find the detailed terminology for the OIDC protocol here, and we 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 is the IAM server at: 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, the Drive at https://drive.ebrains.eu, and any other EBRAINS service including the one you may be adding.
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 OpenID Provider.
Client: A client is an app that can connect to a protected resource on behalf of a user. This is true of any RP. The 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) access her files in the Drive by granting the appropriate 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 the Lab app receives. The Lab can then use this token to connect to the Drive and access 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 identity or authorization information, for example an email address.
Authorization, Roles and EBRAINS Units, Groups, and Teams
This section outlines the EBRAINS structure, and the workflow we suggest for validating identity and managing authorization. IAM manages user accounts. Some users have an official capacity in EBRAINS: e.g. members of the HBP project or of HBP Partnering Projects. They are manually placed in Units according to their role in those projects. Users are also placed automatically within a Unit for their institution, and institutions are organized in Units for their respective countries. Units are distributed in a tree structure. A user member of a Unit X is automatically also a member of all the Units between X and the root of the tree. An admin of a Unit X is automatically an admin of all Units between X and all of its leaves.
Groups can be created and users, Units and other Groups can be assigned to a Group. We recommend that service providers create Groups to manage permissions within their app.
Users register for their EBRAINS account with their institutional email address. Their email is re-verified at regular intervals. users are placed in a Unit corresponding to the institution they belong to, as well as the country where it is headquartered. This is all information pertaining to the user’s identity.
Groups can be used to assign a role to a user or Unit. You can give Alice and all her fellow members of a given Unit a role called e.g. my-‘brain-team-viewer’. Units and Groups are available to services that have created an OIDC client. They can be used to manage permissions within your service.
Units: the Organistational Structure
Units represent organisational structures within EBRAINS: HBP, partners. The HBP SGA3 project defined that accreditations within the project was determined by users being members of Units representing each Task in the project's Work Breakdown Structure. Users request their accreditation 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 for the user in the Task, the parent Work Package and the HBP SGA3 project. The accreditor is responsible for removing the person from the Unit upon departure.
Part of the current structure of Units is the following:
The users' Units under /all/projects are validated manually by the admins of the respective Units. The users' Units under /all/institutions and /all/companies are validated automatically according to the users' registered email address.
Groups: User managed
Users can request a special permission 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 in the Identity app or by querying the userinfo endpoint with the user’s access token.
Teams
A Team is a special group associated with a Collab.
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.
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.