Abstract

OIDC clients and service accounts serve two different purposes. An OIDC client allows an app to authenticate a user and access a user's data, but the OIDC client is not an EBRAINS user. Most functionality within EBRAINS is restricted to actual users. A service account is the embodiment of an actual user for an OIDC client and allows it to take actions as a user.

This page describes the procedure for creating a service account and using it.

Introduction

There are two types of service accounts: EBRAINS service accounts and Fenix Service accounts.

Fenix service accounts are accounts that have been granted Fenix resources (compute, storage) and that are set up to allow EBRAINS users to consume these resources. They exist to avoid that EBRAINS users each have to create a Fenix account and request resources for themselves. The owner of the Fenix service account requests Fenix resources, distributes them to end users, and accepts responsibility for the use/abuse made by the end user of those resources. Fenix service accounts are regular accounts with special terms of use.

EBRAINS supports service accounts. Typically each Fenix service account which is set up for an EBRAINS service has its corresponding EBRAINS service account; the two are paired by their common email address. EBRAINS service accounts can also be used by a service that needs to contact other EBRAINS services.

EBRAINS users that are authorized service developers can create an OIDC client. They can then have a service account created for the OIDC client.

Configure your OIDC Client

Before a service account can be created for an OIDC client, that OIDC client needs to be authorized to create a service account. This can be done at creation of the OIDC client, or by editing an existing OIDC client. See the OIDC client management app at https://wiki.ebrains.eu/bin/view/OIDC. The checkbox for the "service account" field needs to be checked.

For users doing this via the API rather than the OIDC client management app, the instructions are as follows.

EBRAINS service providers need to set "serviceAccountsEnabled" : true in the definition of their OIDC client as documented under How to modify your OIDC client.

Create your service account

Next, the owner of the OIDC client should create the service account. This is done automatically the first time that you request an access token that will be used by the service account to access EBRAINS services. The name of your service account will be "service-account-" followed by the name (i.e. clientId) of your OIDC client.

Service accounts are not findable in the Collaboratory Identity Manager. In Keycloak, service accounts can not be listed from the user search; they are accessible via the Client tab, searching for the OIDC client, and going to the "Service Account Roles" sub-tab.

Get an access token for the service account

Tokens created for service accounts will expire after 7 days. Just as for any other user, multiple tokens can co-exist for a service account, each with its specific scopes.

Endpoint:

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

Parameters in the request body:

• grant_type: "client_credentials"
• client_id: the OIDC clientId
• client_secret: the client secret
• scope: A space separated list of scopes that will be granted to this token. It cannot exceed those available to your OIDC client.

Sample request:

Add roles (permissions) to your service account

Rather than an EBRAINS service restricting access to a list of users, they are encouraged to define one or several roles and to ask that these roles be assigned to users. When more than just a few users will need to be granted the role, a Group can be created, the role is assigned to the Group and users are added/removed from the Group by the Group admin. Those users then inherit the role from the Group.

For some use cases, it's useful to add specific roles to a service account, for instance to give access to collabs, to establish service-to-service communication and/or unsupervised automation scripts.

To add a role to a service account or to add a service account to a Group, service developers can contact EBRAINS Support with the following information:

• an explanation of the request,
• the name of the EBRAINS service that your service account needs to get access to,
• the username of the EBRAINS service account,
• the OIDC client ID used by the service account,
• a confirmation that you have been able to generate an access token via the "client_credentials" flow (see above). Never share a token with other people including EBRAINS support.

Examples:

• I would like to run a Python script every night to read protected information from the EBRAINS Knowledge Graph. To get the permissions to read the protected information, my service account needs to be assigned specific roles or it needs to be added to an existing user group which has been assigned those roles. I therefore request my service account to be assigned the appropriate role X or to be added to the Group Y.

• I have built a service which is consuming information from another EBRAINS service - e.g. to populate a specific index database. I therefore request my service account to be assigned the appropriate role X or to be added to the Group Y.

Add the service account to a Team or Group

Refer to the Team or Group sections in the Collab API  documentation and use the PUT request to add a user (in this case the service account user) to a Team or Group. The figure below shows the PUT request for adding a user to a Team.

You could then check that the service account has effectively been added to the Team or Group in one of several ways:

• use the collab API to list members of a Team or Group
• or create a new access token for the service account, with the "team" or "group" scopes, and check in this new access token which Teams or groups the service account user is a member of. This can be done in the https://jwt.io UI, or programmatically by decoding the token.

From that point on, you will be able to use your service account to interact with your collab or your groups through a Jupyter notebook in the Lab or any scripts.