Version 12.1 by mmorgan on 2022/05/09 17:04
Show last authors
1 Must read before starting
2
3 It's very important to choose the right type of clients and to understand the various OAuth flows.
4
5 A very good documentation is this one :
6
7 [[https:~~/~~/auth0.com/docs/authorization/which-oauth-2-0-flow-should-i-use>>url:https://auth0.com/docs/authorization/which-oauth-2-0-flow-should-i-use]]
8
9 and another one
10
11 [[https:~~/~~/dzone.com/articles/the-right-flow-for-the-job-which-oauth-20-flow-sho>>url:https://dzone.com/articles/the-right-flow-for-the-job-which-oauth-20-flow-sho]]
12
13 == Abstract ==
14
15 This wiki page is for service providers whose apps need to authenticate with the EBRAINS Single Sign-On. EBRAINS users need to be in the [["service providers" Group>>https://wiki.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam--service-providers]] to access to manage an OIDC client.
16
17 A previous version of this documentation explained how to create an OIDC Client using the native Keycloak API. It was a bit complex for users. They had to fetch a specific developer access token, then create the OIDC client, and safely store the registrationAccessToken and safely store a new token after every one of their updates. There were limitations on scope editions. There was no notion of OIDC client ownership making it difficult to manage who could edit settings for the OIDC client. And there was no option to grant access to the OIDC client to a limited set of EBRAINS users.
18 \\All these issues have been solved with the new OIDC Client API provided in the Collaboratory API. OIDC client owners can now use their usual collab access token (e.g. from a notebook in the Collaboratory Lab) to create and manage their OIDC Client. They no longer have to safely store a registrationAccessToken. They can provide a list of maintainers that are allowed to update the OIDC client. And they can also choose which end users can be granted access via their OIDC client.
19 \\This documentation describes the available endpoints and the JSON format excepted by the API. A more concrete example is also provided in a Lab notebook.
20
21 == Lab notebook to create your client ==
22
23 (% class="wikigeneratedid" %)
24 A live example of OIDC Client creation is available **[[here>>https://lab.ch.ebrains.eu/hub/user-redirect/lab/tree/shared/Collaboratory%20Community%20Apps/Managing%20an%20OpenID%20Connect%20client%20-%20V2.ipynb]] **to be run in the Collaboratory Lab.
25
26 (% class="wikigeneratedid" %)
27 The next steps in this documentation reproduce the content of the notebook. We strongly recommend that service providers use this notebook to create their OIDC client. It's the easiest way to avoid any mistake.
28
29 == Endpoints ==
30
31 (% class="box infomessage" %)
32 (((
33 POST :     https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients
34 PUT :     https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}
35 GET   :     https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}
36 )))
37
38 The POST/PUT API endpoints use the same JSON format to describe the OIDC client.
39
40 The GET API endpoint returns a valid JSON format, which can be edited and used to update an OIDC client. It's the recommended way of updating an OIDC client: first fetch your OIDC client's info, then edit the JSON. This reduces the risk of forgetting data in the JSON of POST/PUT call which would delete the missing data from the OIDC client configuration.
41
42 == JSON Format ==
43
44 Find below an example JSON format and an explanation of its fields.
45
46 ----
47
48 {{code language="json"}}
49 {
50 "client": {
51 "clientId": "tutorialOidcApi",
52 "name": "Tutorial OIDC API",
53 "description": "A sample client demo for the OIDC API documentation",
54 "rootUrl": "https://example.org",
55 "baseUrl": "https://example.org",
56 "redirectUris": [
57 "https://example.org/login/*"
58 ],
59 "bearerOnly": false,
60 "consentRequired": true,
61 "standardFlowEnabled": true,
62 "implicitFlowEnabled": false,
63 "directAccessGrantsEnabled": false,
64 "attributes": {
65 "contacts": "first.contact@example.com; second.contact@example.com"
66 },
67 "defaultClientScopes": ["openid", "email"],
68 "optionalClientScopes": ["profile","team","group"]
69 },
70 "maintainers": ["messines","bougault"],
71 "featureAuthenticate" : false,
72 "accessDeniedToGuests" : false
73 }
74 {{/code}}
75
76 === client ===
77
78 The JSON provided to the OIDC app API must contain a "client" object. It's the same JSON as in the previous versions of the documentation using the Keycloak native API. You can use all the attributes available in the ClientRepresentation object natively used by Keycloak and [[described here>>https://www.keycloak.org/docs-api/15.0/rest-api/index.html#_clientrepresentation]].
79
80 === maintainers ===
81
82 This list field is optional. The OIDC client owner can provide a list of maintainers. The values in the list must be valid usernames of EBRAINS users. Even if this field is not provided, the OIDC client can always also be maintained by its owner. An OIDC client is now automatically configured with an owner property which stores the username of the EBRAINS user creating the OIDC client.
83
84 === featureAuthenticate ===
85
86 This boolean field is optional. If it is not provided, it defaults to **false**. If set to true, EBRAINS users will not be able to gain access to your OIDC client unless they are in a Collaboratory Group or Collaboratory Unit which has the "feature:authenticate" role for your OIDC client.
87
88 Service providers wanting to use this feature should set it to true in the JSON request to create/update their OIDC client. They should then use the API endpoints below to grant (PUT) or revoke (DELETE) access.
89
90
91 {{info}}
92 PUT/DELETE: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}/groups/**{groupsName}|**
93 PUT/DELETE: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}/units/**{unitPath}**
94 \\__Example to grant access to HBP members__
95
96 PUT: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/units/**all:projects:hbp**
97
98 __Example to grant access to TVB Workshop attendees__
99
100 PUT: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/groups/**TVB-Workshops**
101 {{/info}}
102
103 EBRAINS users can visit [[https:~~/~~/wiki.ebrains.eu/bin/view/Identity>>https://wiki.ebrains.eu/bin/view/Identity]] and from there browse Units to find the relevant unitPath in the Unit tree.
104
105 A more complete documentation on [[How to grant access is available in the notebook>>https://lab.ch.ebrains.eu/hub/user-redirect/lab/tree/shared/Collaboratory%20Community%20Apps/Managing%20an%20OpenID%20Connect%20client%20-%20V2.ipynb]]. If you don't feel confident in managing specifically access to your client, the easiest is maybe to let your authentication open to all EBRAINS users as it is currently the case by letting //featureAuthenticate //property to false.
106
107
108 __**Warning**__**:** if you switch featureAuthenticate from true to false, all the Group/Unit specific accesses that were configured will be lost and will have to be granted again if you switch from false to true again.
109
110 === accessDeniedToGuests ===
111
112 This boolean field is optional. If it is not provided, it defaults to **true**, meaning that Guest users won't be able to access your OIDC client.
113 \\Service providers who want to provide access to EBRAINS guest accounts can set this field to false. Use of EBRAINS resources by EBRAINS guests accounts is the service provider's responsibility. Guest users might be insufficiently identified, might not be legally liable, might not be part of the target audience of the EBRAINS platform. See [[Guest accounts>>doc:Collabs.the-collaboratory.Documentation Wiki.FAQ.Create guests accounts.WebHome]] for more information before granting such an access and contact [[EBRAINS Support>>https://ebrains.eu/support]] in case of doubt.
114
115 == How to GET and UPDATE your client ==
116
117 Service providers who want to see your OIDC client settings can GET the API endpoint as shown below, with their access token, e.g. the token from the Collaboratory Lab.
118
119
120 GET: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}/
121
122 e.g. GET: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/
123 \\The response will look like:
124
125 {{code language="json"}}
126 {
127 "client": {
128 "id": "tutorialOidcApi",
129 "clientId": "tutorialOidcApi",
130 "name": "Tutorial OIDC API",
131 "description": "A sample client demo for the OIDC API documentation",
132 "rootUrl": "https://example.org",
133 "adminUrl": null,
134 "baseUrl": "https://example.org",
135 "surrogateAuthRequired": false,
136 "enabled": true,
137 "alwaysDisplayInConsole": false,
138 "clientAuthenticatorType": "client-secret",
139 "secret": "IooQSAmrbPUqYgBMPsIBKSF4S58lupUi",
140 "registrationAccessToken": null,
141 "redirectUris": [
142 "https://example.org/login/*"
143 ],
144 "webOrigins": [
145 "https://example.org"
146 ],
147 "bearerOnly": false,
148 "consentRequired": true,
149 "standardFlowEnabled": true,
150 "implicitFlowEnabled": false,
151 "directAccessGrantsEnabled": false,
152 "serviceAccountsEnabled": false,
153 "publicClient": false,
154 "frontchannelLogout": false,
155 "protocol": "openid-connect",
156 "attributes": {
157 "contacts": "first.contact@example.com; second.contact@example.com"
158 },
159 "authenticationFlowBindingOverrides": {},
160 "fullScopeAllowed": false,
161 "nodeReRegistrationTimeout": -1,
162 "registeredNodes": null,
163 "defaultClientScopes": [
164 "openid",
165 "email"
166 ],
167 "optionalClientScopes": [
168 "profile",
169 "team",
170 "group"
171 ],
172 "access": null,
173 "origin": null
174 },
175 "owner": "messines",
176 "maintainers": [
177 "messines",
178 "bougault"
179 ],
180 "accessDeniedToGuests": false,
181 "featureAuthenticate": false,
182 "grantedAccess": {
183 "users": [],
184 "units": [],
185 "groups": []
186 },
187 "featureAuthenticateIntValue": 0,
188 "guestPropertyIntValue": 0
189 }
190 {{/code}}
191
192 Then to update the OIDC client settings, the easiest and recommended way is to copy the JSON received from the GET request, to edit it, and run a PUT request on the OIDC client endpoint with the JSON added as body of the request.
193
194 e.g. PUT: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/
195 \\The following attributes should be removed before resending the JSON to the PUT endpoint, or they will simply be ignored:
196
197 * grantedAccess
198 * featureAuthenticateIntValue
199 * guestPropertyIntValue
200 * owner
201
202 To change the owner of an OIDC client, the current owner should contact [[EBRAINS support>>https://ebrains.eu/support]].
203
204 == Using your new OIDC client as a service account ==
205
206 To use your new OIDC client as a service account, please [[read our tutorial>>path:/bin/view/Collabs/the-collaboratory/Documentation%20IAM/FAQ/Using%20your%20OIDC%20client%20as%20a%20service%20account/]] on how to do this.