Last modified by messines on 2021/06/08 17:32
Hide last authors
messines 22.1 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
messines 1.2 6 == Abstract ==
7
mmorgan 13.1 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.
messines 1.2 9
mmorgan 13.1 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.
messines 1.2 11
mmorgan 13.1 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/*]]
messines 1.2 13
messines 9.1 14 [[image:Screenshot 2020-07-15 at 17.47.12.png||height="517" width="758"]]
messines 1.2 15
messines 2.2 16
mmorgan 13.1 17 The whole authentication flow presented here is based on the official OAuth2 RFC described in the section 4.1.
messines 2.2 18
19 [[https:~~/~~/tools.ietf.org/html/rfc6749#section-4.1>>https://tools.ietf.org/html/rfc6749#section-4.1]]
20
messines 8.1 21 [[image:Screenshot 2020-07-15 at 18.32.14.png||height="410" width="474"]]
22
messines 2.2 23 == Authentication flow ==
24
mmorgan 13.1 25 === Authorization Code Request ===
messines 2.2 26
mmorgan 13.1 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.
messines 11.1 28
messines 2.2 29 ==== Request ====
30
mmorgan 13.1 31 The authorization **code **is fetched by an HTTP request:
messines 2.2 32
mmorgan 13.1 33 /GET: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth]]
messines 2.2 34
mmorgan 13.1 35 with the following parameters:
36
messines 2.2 37 * response_type=code
38 * login=true
mmorgan 13.1 39 * client_id=**//community-apps-tutorial//**
40 * redirect_uri=**//https:~/~/www.getpostman.com/oauth2/callback//**
41 * scope=openid**//+group+team//**
messines 2.2 42
mmorgan 13.1 43 with the italics indicating the fields you customize for your own app. The URL will look like:
messines 2.2 44
mmorgan 13.1 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**//
messines 2.2 46
mmorgan 13.1 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.
messines 2.2 48
mmorgan 13.1 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.
messines 17.6 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.
mmorgan 13.1 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.
messines 17.2 54 * **clb.wiki.read **(optional): access to GET Collab API
messines 17.3 55 * **clb.wiki.write** (optional): access to DELETE/PUT/POST Collab API
messines 18.1 56 * **collab.drive **(optional): access to GET/POST/PUT/DELETE drive API
messines 17.6 57 * **offline_access **(optional)**: **provide refresh token
messines 2.2 58
mmorgan 13.1 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}}
messines 2.2 62
63 ==== Response ====
64
mmorgan 13.1 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:
messines 2.2 66
mmorgan 13.1 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**
messines 2.2 68
69 (% class="box infomessage" %)
70 (((
mmorgan 13.1 71 The authorization **code** is the part in bold in the response above.
messines 2.2 72 )))
73
messines 3.2 74 === Access Token Request ===
75
mmorgan 13.1 76 (% class="wikigeneratedid" id="HRequest-1" %)
messines 19.1 77 Now that your app has the **authorization** **code** for a user, it can fetch the user ID Token and Access Token
mmorgan 13.1 78
messines 3.2 79 ==== Request ====
80
mmorgan 17.1 81 /POST: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token]]
messines 3.2 82
mmorgan 13.1 83 with the following parameters:
messines 3.2 84
mmorgan 13.1 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//**
messines 3.2 90
mmorgan 13.1 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.]
messines 3.2 92
93 [[image:Screenshot 2020-07-15 at 18.20.34.png]]
94
95
96 ==== Response ====
97
98 200 OK
99
100 (% class="box" %)
101 (((
102 {
103 "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAi...pP5vaNwvvsaNGEA",
104 "expires_in": 604773,
105 "refresh_expires_in": 604773,
106 "refresh_token": "eyJh...vC5eIR1rNhRJ4d8",
107 "token_type": "bearer",
108 "id_token": "eyJ...YOwdQ",
109 "not-before-policy": 0,
110 "session_state": "76e553bf-ba2e-45b6-8c6c-c867772b40ec",
111 "scope": "openid"
112 }
113 )))
114
messines 19.1 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.
messines 5.1 116
117 == Access user info ==
118
mmorgan 13.1 119 Now that your app has the access token of a user, it can fetch the user's info.
120
messines 10.1 121 ==== Request ====
122
mmorgan 17.1 123 /GET: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo>>https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo]]
messines 5.1 124
mmorgan 13.1 125 with the following parameters:
messines 5.1 126
mmorgan 13.1 127 * Authorization: the access token preceded by the string "Bearer "
messines 5.1 128
mmorgan 13.1 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
messines 5.1 131 [[image:Screenshot 2020-07-15 at 18.28.28.png||height="161" width="566"]]
132
messines 10.1 133 ==== Response ====
134
mmorgan 16.1 135 As response your app receives a JSON with all the information about the logged user
messines 5.1 136
137 (% class="box" %)
138 (((
139 {
mmorgan 13.1 140 "sub": "fa2db206-3...0ebaba98e1",
messines 5.1 141 "unit": [
142 "/all/institutions/switzerland/epfl",
143 "/all/projects/hbp/consortium/SGA2/SP05",
144 "/all/projects/hbp/consortium/SGA3/WP6/T6_11"
145 ],
146 "roles": {
147 "jupyterhub": [
148 "feature:authenticate"
149 ],
150 "xwiki": [
151 "feature:authenticate"
152 ],
153 "team": [
mmorgan 13.1 154 "**collab**-collaboratory-community-apps-**editor**"
messines 5.1 155 ],
156 "group": [
mmorgan 13.1 157 "**group**-collaboratory-developers",
mmorgan 16.1 158 "**unit**-all-projects-hbp-consortium-sga2-sp05-**administrator**"
messines 5.1 159 ]
160 },
mmorgan 13.1 161 "mitreid-sub": "30...62"
messines 5.1 162 }
163 )))
mmorgan 13.1 164
mmorgan 16.1 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.
mmorgan 13.1 166
mmorgan 16.1 167 jupyterhub and xwiki are OIDC clients with more advanced permission management.
mmorgan 13.1 168
mmorgan 16.1 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//.
mmorgan 13.1 170
mmorgan 16.1 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.