Wiki source code of Authenticating with your OIDC client and fetch collab user info

Version 17.1 by mmorgan on 2020/07/20 19:52

version	line-number	content
1.2	1	== Abstract ==
	2
13.1	3	In order to create an OIDC client, see [[1. Registering an OIDC client>>https://wiki.ebrains.eu/bin/view/Collabs/collaboratory-community-apps/Community%20App%20Developer%20Guide/1.%20Registering%20an%20OIDC%20client/]]. After creating the OIDC client, you have a corresponding access token and secret.
1.2	4
13.1	5	For the example below, we consider the case of someone wanting to provide access to https:~/~/www.getpostman.com as an app for Collaboratory users to access from their collabs. You should replace that URL by the one of your own app.
1.2	6
13.1	7	The redirect_uri is set with the URL of your application to which your users will be redirected after having been authenticated by their EBRAINS account. For example when you login to this wiki, the redirect URI is [[https:~~/~~/wiki.ebrains.eu/>>https://wiki.ebrains.eu/]]
1.2	8
9.1	9	[[image:Screenshot 2020-07-15 at 17.47.12.png\|\|height="517" width="758"]]
1.2	10
2.2	11
13.1	12	The whole authentication flow presented here is based on the official OAuth2 RFC described in the section 4.1.
2.2	13
	14	[[https:~~/~~/tools.ietf.org/html/rfc6749#section-4.1>>https://tools.ietf.org/html/rfc6749#section-4.1]]
	15
8.1	16	[[image:Screenshot 2020-07-15 at 18.32.14.png\|\|height="410" width="474"]]
	17
2.2	18	== Authentication flow ==
	19
13.1	20	=== Authorization Code Request ===
2.2	21
13.1	22	The first step of the authentication protocol is to fetch an authorization code for your client and your user. This is done by directing your users to the URL of the EBRAINS login page (IAM) where they can enter their username and password.
11.1	23
2.2	24	==== Request ====
	25
13.1	26	The authorization code is fetched by an HTTP request:
2.2	27
13.1	28	/GET: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth]]
2.2	29
13.1	30	with the following parameters:
	31
2.2	32	* response_type=code
	33	* login=true
13.1	34	* client_id=//community-apps-tutorial//
	35	* redirect_uri=//https:~/~/www.getpostman.com/oauth2/callback//
	36	* scope=openid//+group+team//
2.2	37
13.1	38	with the italics indicating the fields you customize for your own app. The URL will look like:
2.2	39
13.1	40	https:~/~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth?response_type=code&login=true&client_id=//community-apps-tutorial//&redirect_uri=//https:~/~/www.getpostman.com/oauth2/callback//&scope=openid//+group+team//
2.2	41
13.1	42	The scope parameter can include a combination of several values. Each user will be asked to consent to sharing that scope with your app upon first access.
2.2	43
13.1	44	* openid: This scope is required because we use the OIDC protocol. It will give your app access to the user's basic information such as username, email and full name.
	45	* group (optional): If you request this scope, the future access token generated will authorize your app to identify which units and groups the user belongs to.
	46	* team (optional): This scope is like the group scope lets your app identify the permissions of the user, but by identifying what collabs the user has access to and with what roles.
2.2	47
13.1	48	{{info}}
	49	The group and team scopes are a simple way for your app to grant permissions to its services and resources when you want to grant access to a very few units, groups, or collab teams. For more complex permission management, contact support.
	50	{{/info}}
2.2	51
	52	==== Response ====
	53
13.1	54	Once the user has logged in, your app gets an HTTP 301 redirection followed by an HTTP 200 success response with an authorization code inside. A typical response might look like:
2.2	55
13.1	56	https:~/~/www.getpostman.com/oauth2/callback?session_state=a0ff8a68-2654-43ef-977a-6c15ce343546&code=f3f04f93-hbp-482d-ac3d-demo.turtorial.7122c1d9-3f7e-4d80-9c4f-dcd244bc2ec7
2.2	57
	58	(% class="box infomessage" %)
	59	(((
13.1	60	The authorization code is the part in bold in the response above.
2.2	61	)))
	62
3.2	63	=== Access Token Request ===
	64
13.1	65	(% class="wikigeneratedid" id="HRequest-1" %)
	66	Now that your app has the authorization code for a user, it can fetch the user access token
	67
3.2	68	==== Request ====
	69
17.1	70	/POST: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token]]
3.2	71
13.1	72	with the following parameters:
3.2	73
13.1	74	* grant_type: authorization_code
	75	* code: //f3f04f93-hbp-482d-ac3d-demo.turtorial.7122c1d9-3f7e-4d80-9c4f-dcd244bc2ec7//
	76	* redirect_uri: //[[https:~~/~~/www.getpostman.com/oauth2/callback>>https://www.getpostman.com/oauth2/callback]]//
	77	* client_id: //community-apps-tutorial//
	78	* client_secret: //your client secret obtained during client creation//
3.2	79
13.1	80	The image below shows a sample POST request generated from the Postman tool. [The fact that this page is based on getpostman.com as an example is pure coincidence.]
3.2	81
	82	[[image:Screenshot 2020-07-15 at 18.20.34.png]]
	83
	84
	85	==== Response ====
	86
	87	200 OK
	88
	89	(% class="box" %)
	90	(((
	91	{
	92	"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAi...pP5vaNwvvsaNGEA",
	93	"expires_in": 604773,
	94	"refresh_expires_in": 604773,
	95	"refresh_token": "eyJh...vC5eIR1rNhRJ4d8",
	96	"token_type": "bearer",
	97	"id_token": "eyJ...YOwdQ",
	98	"not-before-policy": 0,
	99	"session_state": "76e553bf-ba2e-45b6-8c6c-c867772b40ec",
	100	"scope": "openid"
	101	}
	102	)))
	103
13.1	104	Your app gets a response containing the access token and other information.
5.1	105
	106	== Access user info ==
	107
13.1	108	Now that your app has the access token of a user, it can fetch the user's info.
	109
10.1	110	==== Request ====
	111
17.1	112	/GET: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo]]
5.1	113
13.1	114	with the following parameters:
5.1	115
13.1	116	* Authorization: the access token preceded by the string "Bearer "
5.1	117
13.1	118	The image below shows a sample GET request generated from the Postman tool. [The fact that this page is based on getpostman.com as an example is pure coincidence.]
	119
5.1	120	[[image:Screenshot 2020-07-15 at 18.28.28.png\|\|height="161" width="566"]]
	121
10.1	122	==== Response ====
	123
16.1	124	As response your app receives a JSON with all the information about the logged user
5.1	125
	126	(% class="box" %)
	127	(((
	128	{
13.1	129	"sub": "fa2db206-3...0ebaba98e1",
5.1	130	"unit": [
	131	"/all/institutions/switzerland/epfl",
	132	"/all/projects/hbp/consortium/SGA2/SP05",
	133	"/all/projects/hbp/consortium/SGA3/WP6/T6_11"
	134	],
	135	"roles": {
	136	"jupyterhub": [
	137	"feature:authenticate"
	138	],
	139	"xwiki": [
	140	"feature:authenticate"
	141	],
	142	"team": [
13.1	143	"collab-collaboratory-community-apps-editor"
5.1	144	],
	145	"group": [
13.1	146	"group-collaboratory-developers",
16.1	147	"unit-all-projects-hbp-consortium-sga2-sp05-administrator"
5.1	148	]
	149	},
13.1	150	"mitreid-sub": "30...62"
5.1	151	}
	152	)))
13.1	153
16.1	154	The unit field above lists Collaboratory Units which the user is a member of, with the unit name using slashes instead of the colons you see in the Collaboratory UI.
13.1	155
16.1	156	jupyterhub and xwiki are OIDC clients with more advanced permission management.
13.1	157
16.1	158	The team field above lists Collaboratory Teams which the user is a member of, in the form "collab-//collabname//-//role//" where //role //is one of admin, editor, or viewer according to the user's role in collab //collabname//.
13.1	159
16.1	160	The group field above lists Collaboratory Groups which the user is a member of, in the form "group-//groupname//". It also lists Collaboratory Units which the user is an admin of, in the form "unit-//unitname//-administrator" with //unitname //using dashes instead of the colons you see in the Collaboratory UI.

Wiki source code of Authenticating with your OIDC client and fetch collab user info

Collaboratory Community Apps