Version 5.1 by mmorgan on 2022/05/06 02:52
Show last authors
1 == Abstract ==
2
3 EBRAINS service accounts can access other EBRAINS services (e.g. the Collaboratory Drive, the Collaboratory API, the Knowledge Graph, ...). Those accounts need to be declared as service accounts and need to generate an access token.
4
5 == Introduction ==
6
7 Service developers can create service accounts. Service accounts perform actions on behalf of a regular user.
8
9 Fenix supports service accounts to provide EBRAINS users access to Fenix resources without those users having Fenix accounts. The owner of the service account requests Fenix resources, distributes them to end users, and accepts responsibility for the use/abuse made by end user of those resources. Fenix service accounts are regular accounts with special terms of use.
10
11 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.
12
13 This page explains how this service access by one EBRAINS service account to other EBRAINS services can be performed.
14
15 == Configure your OIDC Client ==
16
17 The first thing EBRAINS service providers must do is to configure their OIDC client as a service account. They need to set **"serviceAccountsEnabled" : true** in the definition of their OIDC client as documented under [[How to modify your OIDC client.>>doc:Collabs.collab-devs.collaboratory-v2.keycloak.1\. Registering an OIDC client.WebHome]]
18
19 {{code language="json"}}
20 {
21 "defaultClientScopes" : [
22 "web-origins",
23 "roles"
24 ],
25 "redirectUris" : [
26 "/relative/redirect/path",
27 "/these/can/use/wildcards/*"
28 ],
29 ...,
30
31 ...,
32 "serviceAccountsEnabled" : true
33 }
34 {{/code}}
35
36 == Generate an access token ==
37
38 Next, an EBRAINS service provider can generate an access token that will be used for future accesses to other EBRAINS services. This token's expiration is (% style="background-color:#f1c40f" %)TO BE DEFINED(%%).
39
40 ==== Endpoint: ====
41
42 [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token]]
43
44 ==== Parameters in the request body: ====
45
46 * grant_type: "client_credentials"
47 * client_id: the OIDC clientId
48 * client_secret: the client secret
49 * scope: A space separated list of scopes that will be used by this token. It cannot exceed those available to your client.
50
51 ==== Sample request: ====
52
53 {{code language="bash"}}
54 # Request to get an access token
55 curl -X POST https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token \
56 -H 'Content-Type: application/x-www-form-urlencoded' \
57 -d "grant_type=client_credentials&client_id=myclient&client_secret=mysecret&scope=email%20profile%20team%20group%20clb.wiki.read%20clb.wiki.write"
58
59 {{/code}}
60
61 == Add roles to your service account ==
62
63 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.
64
65 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-2-service communication and/or unsupervised automation scripts.
66
67
68 To add a role to a service account or to add a service account to a Group, service developers can contact [[EBRAINS Support>>url:https://ebrains.eu/support]] with the following information:
69
70 * an explanation of the request,
71 * the name of the EBRAINS service that your service account needs to get access to,
72 * the username of the EBRAINS service account,
73 * the OIDC client ID used by the service account,
74 * 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.
75
76
77 Examples:
78
79 * (((
80 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.
81 )))
82 * (((
83 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.
84 )))
85
86