Wiki source code of 1. Registering an OIDC client

Last modified by chaney08 on 2023/02/09 11:14

version	line-number	content
18.1	1	== OAuth 2 Flows ==
	2
9.1	3	Must read before starting
	4
	5	It's very important to choose the right type of clients and to understand the various OAuth flows.
	6
	7	A very good documentation is this one :
	8
	9	[[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]]
	10
	11	and another one
	12
	13	[[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]]
	14
16.1	15	Here is a quick summary of which flow is designed to be used in a given scenario:
	16
17.1	17	* server-to-server (Client Credentials Flow):
	18	** standardFlowEnabled : false
	19	** consentRequired : false
	20	** redirectUri empty
	21	** serviceAccountEnabled : true
	22
	23	so user can't login with this client, [[and the client must have the serviceAccount property set to true >>https://wiki.ebrains.eu/bin/view/Collabs/the-collaboratory/Documentation%20IAM/FAQ/Using%20your%20OIDC%20client%20as%20a%20service%20account/]]
	24
20.1	25	* server-side app (Authorization Code Flow also called Standard Flow, it's the regular flow to establish a login page on your website accessible by your users):
17.1	26	** standardFlowEnabled : true
	27	** consentRequired : true
	28	** redirectUri : not empty, not localhost, https only
	29
20.1	30	* SPA: Single-Page-Application, basically app without backend, public client with Authorization Code Flow and PKCE enforcement by us
17.1	31	** publicClient : true
	32	** standardFlowEnabled : true
	33	** consentRequired : true
	34	** redirectUri : not empty, not localhost, https only
	35
16.1	36	* mobile: Authorization Code Flow
19.1	37	** Same as SPA public or confidential depending if the mobile App use a backend
16.1	38
21.1	39	Note : We are not allowing Implicit Flow, we are not allowing Standard flow without consentRequired and redirectUri either, for security reason. FYI, your public client for SPA usage will be enforced automatically by us with the [[PKCE>>https://oauth.net/2/pkce/]] feature.
20.1	40
5.1	41	== Abstract ==
1.1	42
5.1	43	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.
1.1	44
5.1	45	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.
	46	\\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.
	47	\\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.
	48
26.1	49	== UI to create and manage your clients ==
	50
27.1	51	The newest addition to the OIDC client creation process on the Collaboratory is a UI to help you manage, create and update your clients. You can find this by visiting [[https:~~/~~/wiki.ebrains.eu/bin/view/OIDC/>>https://wiki.ebrains.eu/bin/view/OIDC/]].
26.1	52	\\To create a new OIDC client click on the "Create new client" button as shown in the following image~:
	53
	54	[[image:image-20230209111255-1.png]]
	55
	56	(% class="wikigeneratedid" %)
	57	The UI will explain all of the options you can choose from. To update any client alraedy existing, click on the client in the list. For example, in the above example, if I wanted to update the client "pauls test client" I would click on that entry in the list.
	58
15.1	59	== Lab notebook to create and manage your client ==
1.4	60
	61	(% class="wikigeneratedid" %)
11.1	62	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.
1.4	63
5.1	64	(% class="wikigeneratedid" %)
	65	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.
1.4	66
22.1	67
	68	== Create a localhost client for developement on our integration enviroment ==
	69
	70	You can't create client with redirectUri localhost in production. If you want to create a client for development purpose, please use our integration environement
	71	\\Registration on integration environement : [[https:~~/~~/iam-int.ebrains.eu/register>>https://iam-int.ebrains.eu/register]]
	72
	73
	74	Wiki group to access lab : [[https:~~/~~/wiki-int.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-lab~~-~~-access>>https://wiki-int.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-lab--access]]
23.1	75	Wiki group to access OIDC API : [[https:~~/~~/wiki-int.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam~~-~~-service-providers>>https://wiki-int.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam--service-providers]]
22.1	76
23.1	77	For now, contact our support to be granted on lab-int and get developer accreditation
22.1	78	\\Notebook to create client : [[https:~~/~~/lab-int.ebrains.eu/hub/user-redirect/lab/tree/shared/%EF%BB%BFThe%20Collaboratory/Managing%20an%20OpenID%20Connect%20client%20-%20V2.ipynb>>https://lab-int.ebrains.eu/hub/user-redirect/lab/tree/shared/%EF%BB%BFThe%20Collaboratory/Managing%20an%20OpenID%20Connect%20client%20-%20V2.ipynb]]
	79
1.1	80	== Endpoints ==
	81
	82	(% class="box infomessage" %)
	83	(((
	84	POST : https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients
	85	PUT : https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}
	86	GET : https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}
	87	)))
	88
5.1	89	The POST/PUT API endpoints use the same JSON format to describe the OIDC client.
1.1	90
5.1	91	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.
1.1	92
	93	== JSON Format ==
	94
5.1	95	Find below an example JSON format and an explanation of its fields.
	96
1.1	97	----
	98
	99	{{code language="json"}}
	100	{
	101	"client": {
	102	"clientId": "tutorialOidcApi",
	103	"name": "Tutorial OIDC API",
	104	"description": "A sample client demo for the OIDC API documentation",
	105	"rootUrl": "https://example.org",
	106	"baseUrl": "https://example.org",
	107	"redirectUris": [
	108	"https://example.org/login/*"
	109	],
	110	"bearerOnly": false,
	111	"consentRequired": true,
	112	"standardFlowEnabled": true,
	113	"implicitFlowEnabled": false,
	114	"directAccessGrantsEnabled": false,
	115	"attributes": {
	116	"contacts": "first.contact@example.com; second.contact@example.com"
	117	},
	118	"defaultClientScopes": ["openid", "email"],
	119	"optionalClientScopes": ["profile","team","group"]
	120	},
	121	"maintainers": ["messines","bougault"],
	122	"featureAuthenticate" : false,
	123	"accessDeniedToGuests" : false
	124	}
	125	{{/code}}
1.2	126
1.3	127	=== client ===
	128
5.1	129	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]].
1.3	130
	131	=== maintainers ===
	132
5.1	133	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.
1.3	134
	135	=== featureAuthenticate ===
	136
5.1	137	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.
	138
	139	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.
1.3	140
	141
	142	{{info}}
24.1	143	PUT/DELETE: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}/groups/{groupsName}
	144
	145
5.1	146	PUT/DELETE: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}/units/{unitPath}
	147	\\__Example to grant access to HBP members__
1.3	148
5.1	149	PUT: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/units/all:projects:hbp
	150
	151	__Example to grant access to TVB Workshop attendees__
	152
	153	PUT: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/groups/TVB-Workshops
1.3	154	{{/info}}
	155
7.1	156	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.
1.4	157
12.1	158	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.
7.1	159
	160
	161	__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.
	162
1.4	163	=== accessDeniedToGuests ===
	164
5.1	165	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.
	166	\\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.
2.1	167
	168	== How to GET and UPDATE your client ==
	169
5.1	170	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.
2.1	171
	172
5.1	173	GET: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}/
2.1	174
5.1	175	e.g. GET: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/
	176	\\The response will look like:
3.1	177
	178	{{code language="json"}}
	179	{
2.1	180	"client": {
	181	"id": "tutorialOidcApi",
	182	"clientId": "tutorialOidcApi",
	183	"name": "Tutorial OIDC API",
	184	"description": "A sample client demo for the OIDC API documentation",
	185	"rootUrl": "https://example.org",
	186	"adminUrl": null,
	187	"baseUrl": "https://example.org",
	188	"surrogateAuthRequired": false,
	189	"enabled": true,
	190	"alwaysDisplayInConsole": false,
	191	"clientAuthenticatorType": "client-secret",
14.1	192	"secret": "IooQSAmrbPUqYgHdkklBMPsIBKlupUi",
2.1	193	"registrationAccessToken": null,
	194	"redirectUris": [
	195	"https://example.org/login/*"
	196	],
	197	"webOrigins": [
	198	"https://example.org"
	199	],
	200	"bearerOnly": false,
	201	"consentRequired": true,
	202	"standardFlowEnabled": true,
	203	"implicitFlowEnabled": false,
	204	"directAccessGrantsEnabled": false,
	205	"serviceAccountsEnabled": false,
	206	"publicClient": false,
	207	"frontchannelLogout": false,
	208	"protocol": "openid-connect",
	209	"attributes": {
	210	"contacts": "first.contact@example.com; second.contact@example.com"
	211	},
	212	"authenticationFlowBindingOverrides": {},
	213	"fullScopeAllowed": false,
	214	"nodeReRegistrationTimeout": -1,
	215	"registeredNodes": null,
	216	"defaultClientScopes": [
	217	"openid",
	218	"email"
	219	],
	220	"optionalClientScopes": [
	221	"profile",
	222	"team",
	223	"group"
	224	],
	225	"access": null,
	226	"origin": null
	227	},
	228	"owner": "messines",
	229	"maintainers": [
	230	"messines",
	231	"bougault"
	232	],
	233	"accessDeniedToGuests": false,
	234	"featureAuthenticate": false,
	235	"grantedAccess": {
	236	"users": [],
	237	"units": [],
	238	"groups": []
	239	},
	240	"featureAuthenticateIntValue": 0,
	241	"guestPropertyIntValue": 0
3.1	242	}
	243	{{/code}}
	244
5.1	245	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.
4.1	246
5.1	247	e.g. PUT: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/
8.1	248	\\The following attributes should be removed before resending the JSON to the PUT endpoint, or they will simply be ignored:
2.1	249
5.1	250	* grantedAccess
	251	* featureAuthenticateIntValue
	252	* guestPropertyIntValue
	253	* owner
	254
	255	To change the owner of an OIDC client, the current owner should contact [[EBRAINS support>>https://ebrains.eu/support]].
	256
9.1	257	== Using your new OIDC client as a service account ==
	258
	259	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.

Wiki source code of 1. Registering an OIDC client

The Collaboratory