Attention: The Keycloak upgrade has been completed. As this was a major upgrade, there may be some unexpected issues occurring. Please report any issues you find to support by using the contact form found at https://www.ebrains.eu/contact/. Thank you for your patience and understanding. 


Last modified by messines on 2021/06/08 17:32
From version 22.1
edited by messines
on 2021/06/08 17:32
Change comment: There is no comment for this version
To version 8.1
edited by messines
on 2020/07/15 18:33
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -2. Authenticating with your OIDC client and fetch collab user info
1 +Authenticating with your OIDC client and fetch collab user info
Content
... ... @@ -1,20 +6,15 @@
1 -(% class="wikigeneratedid" %)
2 -== Requirement ==
3 -
4 -You should read this documentation to [[understand the concept of Authentication and Authorization>>https://wiki.ebrains.eu/bin/view/Collabs/the-collaboratory/Technical%20documentation/Architecture/Permissions/Authentication%20%26%20Authorisation%20using%20OIDC/]] with OIDC and OAuth2 before to try to implement it.
5 -
6 6  == Abstract ==
7 7  
8 -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.
3 +You had been creating an OIDC client following our guide [[https:~~/~~/wiki.ebrains.eu/bin/view/Collabs/collaboratory-community-apps/Community%20App%20Developer%20Guide/Registering%20an%20OIDC%20client/>>https://wiki.ebrains.eu/bin/view/Collabs/collaboratory-community-apps/Community%20App%20Developer%20Guide/Registering%20an%20OIDC%20client/]]
9 9  
10 -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.
5 +The redirect_uri is set with the url of your application, in this exemple we will use postman, a platform for api developement, use your own application, for exemple when you loggin to this wiki, the redirect uri is [[https:~~/~~/wiki.ebrains.eu/*>>https://wiki.ebrains.eu/*]]
11 11  
12 -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/*]]
7 +The client is confidential with a secret, you obtain it throught the registering oidc client tutorial above.
13 13  
14 -[[image:Screenshot 2020-07-15 at 17.47.12.png||height="517" width="758"]]
9 +[[image:Screenshot 2020-07-15 at 17.47.12.png||height="453" width="664"]]
15 15  
16 16  
17 -The whole authentication flow presented here is based on the official OAuth2 RFC described in the section 4.1.
12 +The whole authentication flow presented here is based on the official OAuth2 rfc describe in the section 4.1
18 18  
19 19  [[https:~~/~~/tools.ietf.org/html/rfc6749#section-4.1>>https://tools.ietf.org/html/rfc6749#section-4.1]]
20 20  
... ... @@ -22,73 +22,63 @@
22 22  
23 23  == Authentication flow ==
24 24  
25 -=== Authorization Code Request ===
20 +=== Authorization Code Grant ===
26 26  
27 -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.
28 -
29 29  ==== Request ====
30 30  
31 -The authorization **code **is fetched by an HTTP request:
24 +/GET on [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth >>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth]]
32 32  
33 -/GET: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth]]
26 +with query parameters
34 34  
35 -with the following parameters:
36 -
37 37  * response_type=code
29 +* client_id=community-apps-tutorial
30 +* redirect_uri=[[https:~~/~~/www.getpostman.com/oauth2/callback>>https://www.getpostman.com/oauth2/callback]]
38 38  * login=true
39 -* client_id=**//community-apps-tutorial//**
40 -* redirect_uri=**//https:~/~/www.getpostman.com/oauth2/callback//**
41 -* scope=openid**//+group+team//**
32 +* scope=openid+group+team
42 42  
43 -with the italics indicating the fields you customize for your own app. The URL will look like:
34 +so
44 44  
45 -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**//
36 +[[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth?response_type=code&client_id=community-apps-tutorial&redirect_uri=https:~~/~~/www.getpostman.com/oauth2/callback&login=true&scope=openid+group+team>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth?response_type=code&client_id=community-apps-tutorial&redirect_uri=https://www.getpostman.com/oauth2/callback&login=true&scope=openid+group+team]]
46 46  
47 -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.
38 +Of course replace **client_id** and **redirect_uri** with your own configuration
48 48  
49 -* **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.
50 -* **profile** (optional): More information on user if provided by the user
51 -* **email **(optional): The verified email of the user, should be add in addition of openid and/or profile to get the email.
52 -* **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.
53 -* **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.
54 -* **clb.wiki.read **(optional): access to GET Collab API
55 -* **clb.wiki.write** (optional): access to DELETE/PUT/POST Collab API
56 -* **collab.drive **(optional): access to GET/POST/PUT/DELETE drive API
57 -* **offline_access **(optional)**: **provide refresh token
40 +This will redirect you to the login page of **iam **where your user must enter they username/password
58 58  
59 -{{info}}
60 -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.
61 -{{/info}}
42 +==== Scope ====
62 62  
44 +In the request you can see a scope **parameter**
45 +
46 +* **openid : **This scope is required in oidc, it contains basic information of the user such as it username, email and full name.
47 +* **group **( optional ) **: **This scope is provided by our service, if you add it to your authorization code grant request, the futur access token generated will be able to read which units and groups the logged user belongs, it can be very important for your application. You can notice on the screenshot in the abstract section that **Consent required **is **on, **it means that at loggin time, the user will be asked if he allow your application to access there unit and group membership
48 +* **team **( optional ) **: **Very same than group, but for collab, with this scope your application will know in which collab the authenticated user belong
49 +
63 63  ==== Response ====
64 64  
65 -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:
52 +After the loggin, you got a 301 redirection and 200 success http response with a **code** inside
66 66  
67 -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**
54 +[[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>>https://www.getpostman.com/oauth2/callback?session_state=a0ff8a68-2654-43ef-977a-6c15ce598886&code=f3f04f93-b98d-482d-ac3d-414cead54de0.a0ff8a68-2654-43ef-977a-6c15ce598886.7122c1d9-3f7e-4d80-9c4f-dcd244bc2ec7]]
68 68  
69 69  (% class="box infomessage" %)
70 70  (((
71 -The authorization **code** is the part in bold in the response above.
58 +the code is very important for the next step here the code is //f3f04f93-hbp-482d-ac3d-demo.turtorial.7122c1d9-3f7e-4d80-9c4f-dcd244bc2ec7//
72 72  )))
73 73  
61 +
74 74  === Access Token Request ===
75 75  
76 -(% class="wikigeneratedid" id="HRequest-1" %)
77 -Now that your app has the **authorization** **code** for a user, it can fetch the user ID Token and Access Token
78 -
79 79  ==== Request ====
80 80  
81 -/POST: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token]]
66 +Now that you have the **authorization** **code, **you can reach the **/token **endpoint and fetch the user access token
82 82  
83 -with the following parameters:
68 +/POST : https:/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token
84 84  
85 -* grant_type: authorization_code
86 -* code: **//f3f04f93-hbp-482d-ac3d-demo.turtorial.7122c1d9-3f7e-4d80-9c4f-dcd244bc2ec7//**
87 -* redirect_uri: **//[[https:~~/~~/www.getpostman.com/oauth2/callback>>https://www.getpostman.com/oauth2/callback]]//**
88 -* client_id: **//community-apps-tutorial//**
89 -* client_secret: **//your client secret obtained during client creation//**
70 +with params
90 90  
91 -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.]
72 +* grant_type : authorization_code
73 +* code : //f3f04f93-hbp-482d-ac3d-demo.turtorial.7122c1d9-3f7e-4d80-9c4f-dcd244bc2ec7//
74 +* redirect_uri : [[https:~~/~~/www.getpostman.com/oauth2/callback>>https://www.getpostman.com/oauth2/callback]]
75 +* client_id : community-apps-tutorial
76 +* client_secret : your client secret obtained during client creation
92 92  
93 93  [[image:Screenshot 2020-07-15 at 18.20.34.png]]
94 94  
... ... @@ -112,33 +112,31 @@
112 112  }
113 113  )))
114 114  
115 -Your app gets a response containing the **access token**, the **refresh token,** the **id token **and other information. The ID Token should be use by developer on their backend to read user informations such as username, first name, last name etc. The ID Token should be use internally, into your app only, the app which triggered the authentication. The access token will be use to reach APIs, the access token can be see as a card to access an ATM. ID Token is for Authentication, Access token is for Authorization. Refresh token is to re-ask a valid access token after expiration.
100 +You get a response containing the access token and others
116 116  
117 117  == Access user info ==
118 118  
119 -Now that your app has the access token of a user, it can fetch the user's info.
104 +Now that your application got the access token of your user, it's really easy to fetch user info
120 120  
121 -==== Request ====
106 +(% class="box infomessage" %)
107 +(((
108 +/GET https:/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo
109 +)))
122 122  
123 -/GET: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo]]
111 +and just provide the access token as **Authentication** header
124 124  
125 -with the following parameters:
126 -
127 -* Authorization: the access token preceded by the string "Bearer "
128 -
129 -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.]
130 -
131 131  [[image:Screenshot 2020-07-15 at 18.28.28.png||height="161" width="566"]]
132 132  
133 -==== Response ====
134 134  
135 -As response your app receives a JSON with all the information about the logged user
116 +As response you will have a json with all the information on the logged user, for my user
136 136  
137 137  (% class="box" %)
138 138  (((
139 139  {
140 - "sub": "fa2db206-3...0ebaba98e1",
121 + "sub": "fa2db206-3eb4-403c-894a-810ebaba98e1",
141 141   "unit": [
123 + "/collab-devs",
124 + "/collab-team",
142 142   "/all/institutions/switzerland/epfl",
143 143   "/all/projects/hbp/consortium/SGA2/SP05",
144 144   "/all/projects/hbp/consortium/SGA3/WP6/T6_11"
... ... @@ -151,21 +151,13 @@
151 151   "feature:authenticate"
152 152   ],
153 153   "team": [
154 - "**collab**-collaboratory-community-apps-**editor**"
137 + "collab-collaboratory-community-apps-editor"
155 155   ],
156 156   "group": [
157 - "**group**-collaboratory-developers",
158 - "**unit**-all-projects-hbp-consortium-sga2-sp05-**administrator**"
140 + "group-collaboratory-developers",
141 + "unit-all-projects-hbp-consortium-sga2-sp05-administrator"
159 159   ]
160 160   },
161 - "mitreid-sub": "30...62"
144 + "mitreid-sub": "305862"
162 162  }
163 163  )))
164 -
165 -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.
166 -
167 -jupyterhub and xwiki are OIDC clients with more advanced permission management.
168 -
169 -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//.
170 -
171 -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.