Last modified by chaney08 on 2023/04/28 14:53
Hide last authors
chaney08 1.1 1 == Requirement ==
2
chaney08 5.1 3 You should read this documentation to [[understand the concept of Authentication and Authorization>>doc:Collabs.the-collaboratory.Documentation IAM.FAQ.OIDC Clients explained.WebHome]] with OIDC and OAuth2 before trying to implement it.
chaney08 1.1 4
5 == Abstract ==
6
messines 11.1 7 In order to create an OIDC client, see [[1. Registering an OIDC client>>doc:Collabs.the-collaboratory.Documentation IAM.FAQ.OIDC Clients explained.1\. Registering an OIDC client v2.WebHome]]. After creating the OIDC client, you have a corresponding access token and secret.
chaney08 1.1 8
9 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.
10
11 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/*>>url:https://wiki.ebrains.eu/*]]
12
13 [[image:https://wiki.ebrains.eu/bin/download/Collabs/collaboratory-community-apps/Community%20App%20Developer%20Guide/Authenticating%20with%20your%20OIDC%20client%20and%20fetch%20collab%20user%20info/WebHome/Screenshot%202020-07-15%20at%2017.47.12.png?width=758&height=517&rev=1.1||alt="Screenshot 2020-07-15 at 17.47.12.png" height="517" width="758"]]
14
15 The whole authentication flow presented here is based on the official OAuth2 RFC described in the section 4.1.
16
17 [[https:~~/~~/tools.ietf.org/html/rfc6749#section-4.1>>url:https://tools.ietf.org/html/rfc6749#section-4.1]]
18
19 [[image:https://wiki.ebrains.eu/bin/download/Collabs/collaboratory-community-apps/Community%20App%20Developer%20Guide/Authenticating%20with%20your%20OIDC%20client%20and%20fetch%20collab%20user%20info/WebHome/Screenshot%202020-07-15%20at%2018.32.14.png?width=474&height=410&rev=1.2||alt="Screenshot 2020-07-15 at 18.32.14.png" height="410" width="474"]]
20
21 == Authentication flow ==
22
23 === Authorization Code Request ===
24
25 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.
26
27 ==== Request ====
28
29 The authorization **code **is fetched by an HTTP request:
30
31 /GET: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth>>url:https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth]]
32
33 with the following parameters:
34
35 * response_type=code
36 * login=true
37 * client_id=**//community-apps-tutorial//**
38 * redirect_uri=**//https:~/~/www.getpostman.com/oauth2/callback//**
39 * scope=openid**//+group+team//**
40
41 with the italics indicating the fields you customize for your own app. The URL will look like:
42
43 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**//
44
45 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.
46
47 * **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.
48 * **profile** (optional): More information on user if provided by the user
49 * **email **(optional): The verified email of the user, should be add in addition of openid and/or profile to get the email.
50 * **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.
51 * **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.
52 * **clb.wiki.read **(optional): access to GET Collab API
53 * **clb.wiki.write** (optional): access to DELETE/PUT/POST Collab API
54 * **collab.drive **(optional): access to GET/POST/PUT/DELETE drive API
messines 23.1 55 * **offline_access **(optional)**: **[[See description here>>https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/sessions/offline.html]]
messines 11.2 56 * **quota : **User's quota usage around EBRAINS services
chaney08 1.1 57
58 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.
59
60 ==== Response ====
61
62 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:
63
64 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**
65
66 The authorization **code** is the part in bold in the response above.
67
68 === Access Token Request ===
69
70 Now that your app has the **authorization** **code** for a user, it can fetch the user ID Token and Access Token
71
72 ==== Request ====
73
74 /POST: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token>>url:https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token]]
75
76 with the following parameters:
77
78 * grant_type: authorization_code
79 * code: **//f3f04f93-hbp-482d-ac3d-demo.turtorial.7122c1d9-3f7e-4d80-9c4f-dcd244bc2ec7//**
80 * redirect_uri: **//[[https:~~/~~/www.getpostman.com/oauth2/callback>>url:https://www.getpostman.com/oauth2/callback]]//**
81 * client_id: **//community-apps-tutorial//**
82 * client_secret: **//your client secret obtained during client creation//**
83
84 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.]
85
86 [[image:https://wiki.ebrains.eu/bin/download/Collabs/collaboratory-community-apps/Community%20App%20Developer%20Guide/Authenticating%20with%20your%20OIDC%20client%20and%20fetch%20collab%20user%20info/WebHome/Screenshot%202020-07-15%20at%2018.20.34.png?rev=1.1||alt="Screenshot 2020-07-15 at 18.20.34.png"]]
87
88 ==== Response ====
89
90 200 OK
91
92 {
93 "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAi...pP5vaNwvvsaNGEA",
94 "expires_in": 604773,
95 "refresh_expires_in": 604773,
96 "refresh_token": "eyJh...vC5eIR1rNhRJ4d8",
97 "token_type": "bearer",
98 "id_token": "eyJ...YOwdQ",
99 "not-before-policy": 0,
100 "session_state": "76e553bf-ba2e-45b6-8c6c-c867772b40ec",
101 "scope": "openid"
102 }
103
104 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.
105
106 == Access user info ==
107
108 Now that your app has the access token of a user, it can fetch the user's info.
109
messines 18.1 110 === Request ===
chaney08 1.1 111
112 /GET: [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo>>url:https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo]]
113
114 with the following parameters:
115
116 * Authorization: the access token preceded by the string "Bearer "
117
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
120 [[image:https://wiki.ebrains.eu/bin/download/Collabs/collaboratory-community-apps/Community%20App%20Developer%20Guide/Authenticating%20with%20your%20OIDC%20client%20and%20fetch%20collab%20user%20info/WebHome/Screenshot%202020-07-15%20at%2018.28.28.png?width=566&height=161&rev=1.1||alt="Screenshot 2020-07-15 at 18.28.28.png" height="161" width="566"]]
121
messines 18.1 122 === Response ===
chaney08 1.1 123
124 As response your app receives a JSON with all the information about the logged user
125
126 {
messines 17.1 127 (% style="color:#2980b9" %)"**sub**": "fa2db206-3...0ebaba98e1",
messines 15.1 128 (% style="color:#27ae60" %)"**preferred_username**": "demoaccount",(%%)
chaney08 1.1 129 "unit": [
130 "/all/institutions/switzerland/epfl",
131 "/all/projects/hbp/consortium/SGA2/SP05",
132 "/all/projects/hbp/consortium/SGA3/WP6/T6_11"
133 ],
134 "roles": {
135 "jupyterhub": [
136 "feature:authenticate"
137 ],
138 "xwiki": [
139 "feature:authenticate"
140 ],
141 "team": [
142 "**collab**-collaboratory-community-apps-**editor**"
143 ],
144 "group": [
145 "**group**-collaboratory-developers",
146 "**unit**-all-projects-hbp-consortium-sga2-sp05-**administrator**"
147 ]
148 },
149 "mitreid-sub": "30...62"
150 }
151
152 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.
153
154 jupyterhub and xwiki are OIDC clients with more advanced permission management.
155
156 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//.
157
158 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.
159
messines 18.1 160 ===
161 Which unique identifier should you use for your users ===
messines 2.2 162
mmorgan 21.1 163 We recommend that you use the "(% style="color:#27ae60" %)preferred_username(%%)" field (i.e. the EBRAINS username) to identify your users for every new user in your service. The "(% style="color:#27ae60" %)preferred_username(%%)" is used as a unique identifier in The Collaboratory, it's the more user friendly way to reference users and interact easily with the Identity Manager (IDM) API. We are guarantying its unicity.
messines 13.1 164
mmorgan 21.1 165 You can also use the "(% style="color:#2980b9" %)sub(%%)" field provided by Keycloak which is the OIDC/OAuth2 standard unique identifier for a user and might be considered as a good choice. If in addition you store the username associated to the sub, you will still be able to easily use the Collaboratory IDM API; otherwise, you might need to perform an additional API request to get the User object from a given sub in the [[IDM API>>doc:Collabs.the-collaboratory.Documentation Wiki.API.WebHome]]
messines 13.1 166
chaney08 24.1 167 You can find additional information about userinfo fields and the difference with previous Collaboratory 1 [[here>>doc:Collabs.the-collaboratory.Documentation IAM.FAQ.OIDC Clients explained.Migrating your OIDC client from Collaboratory 1 to Collaboratory 2.WebHome]]. This will also help you if you want to keep compatibility with your previous OIDC implementation in Collaboratory 1.
messines 13.1 168
mmorgan 21.1 169 == OIDC Plugin configuration example ==
messines 2.2 170
mmorgan 21.1 171 You will probably not reinvent the wheel and use an existing OIDC Library to establish the authentication. Often theses libraries do all the above flow for you; you just have to fill a property file.
messines 2.2 172
mmorgan 21.1 173 === OIDC Plugin Properties: useful link ===
messines 2.2 174
mmorgan 21.1 175 All the links you need to fill the property file of your OIDC plugin are visible here:
messines 2.2 176
177 [[https:~~/~~/iam.ebrains.eu/auth/realms/hbp/.well-known/openid-configuration>>https://iam.ebrains.eu/auth/realms/hbp/.well-known/openid-configuration]]
178
mmorgan 21.1 179 === OIDC Plugin for Python: mozilla-django-oidc ===
messines 2.2 180
messines 4.1 181 We are using this plugin with our Django based project, a full documentation is available here
messines 2.2 182 [[https:~~/~~/mozilla-django-oidc.readthedocs.io/en/stable/installation.html>>https://mozilla-django-oidc.readthedocs.io/en/stable/installation.html]]
183
messines 9.1 184
mmorgan 21.1 185 ==== Github demo project using mozilla-django-oidc ====
messines 9.1 186
mmorgan 21.1 187 You can find a very basic empty Django project using mozilla-django-oidc on this github:
messines 10.1 188
mmorgan 21.1 189 [[https:~~/~~/github.com/HumanBrainProject/mozilla-django-oidc-demo>>https://github.com/HumanBrainProject/mozilla-django-oidc-demo]]
messines 9.1 190
mmorgan 21.1 191 Clone it and follow the README instructions. In a few minutes, if you already have an OIDC clientId and clientSecret available, you should be able to login with this demo application. Once you have validated that your client works well, you can compare with your own code and debug your own code to fix potential authentication issues.
messines 9.1 192
mmorgan 21.1 193 In the future, we will add a branch in this github project with advanced usage examples such as overriding the default mozilla-django-oidc class and to fetch the teams, groups and units of a user.
194 \\For now, you can find more advanced usage in the CodeJam#12 presentation regarding [[OIDC integration for Python>>https://drive.ebrains.eu/lib/cf5b0375-4e07-4e62-847d-e2997eac3f30/file/CodeJam%20%2312%20(2021)/Presentations/Oidc_integration_for_python.pptx]].
messines 9.1 195
mmorgan 21.1 196 You can see every function of the original mozilla-django-oidc on that github project, so you can better understand what you can override and how:
197 [[https:~~/~~/github.com/mozilla/mozilla-django-oidc/blob/master/mozilla_django_oidc/auth.py>>https://github.com/mozilla/mozilla-django-oidc/blob/master/mozilla_django_oidc/auth.py]]
messines 9.1 198
199
messines 2.2 200 ==== mozilla-django-oidc sample config ====
201
202 {{code}}
messines 8.1 203 # Mozilla django oidc settings
messines 7.1 204 OIDC_OP_AUTHORIZATION_ENDPOINT = "https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth"
205 OIDC_OP_TOKEN_ENDPOINT = "https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token"
206 OIDC_OP_USER_ENDPOINT = "https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo"
207 OIDC_RP_SIGN_ALGO ="RS256"
208 OIDC_OP_JWKS_ENDPOINT="https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/certs"
209 LOGIN_REDIRECT_URL = '/'
210 OIDC_STORE_ACCESS_TOKEN = True
messines 2.2 211
messines 7.1 212 # Store secret somewhere on your system
messines 9.1 213 OIDC_RP_SCOPES="openid profile email"
messines 7.1 214 OIDC_RP_CLIENT_ID = os.environ['OIDC_RP_CLIENT_ID']
215 OIDC_RP_CLIENT_SECRET = os.environ['OIDC_RP_CLIENT_SECRET']
messines 2.2 216
messines 8.1 217 # Theses one are situational, you problably don't need them, it's to use in the case you want to override an action in a python class, for exemple execute some code after the callback
messines 2.2 218
messines 8.1 219 OIDC_CALLBACK_CLASS = 'clb_auth.views.OIDCAuthenticationCallbackView'
220 OIDC_DRF_AUTH_BACKEND = 'clb_auth.auth.OIDCBearerAuthenticationBackend'
221 OIDC_OP_LOGOUT_URL_METHOD = 'clb_auth.auth.logout_url'
messines 2.2 222
223 {{/code}}
224
225
mmorgan 21.1 226 === OIDC Plugin for Python: flask-oidc ===
messines 2.2 227
228 [[https:~~/~~/flask-oidc.readthedocs.io/en/latest/>>https://flask-oidc.readthedocs.io/en/latest/]]
229
messines 3.1 230 You will need at the root of your project a "client_secrets.json" file.
231
messines 2.3 232 ==== ====
233
messines 3.1 234 client_secrets.json
messines 2.3 235
messines 3.1 236 {{code language="json"}}
237 {
238 "web": {
239 "client_id": "yourClientId",
240 "client_secret": "yourClientSecret",
241 "redirect_uris": [
242 "http://localhost:8081/",
243 "https://yourappurl.url/"
244 ],
245 "auth_uri": "https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/auth",
246 "token_uri": "https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token",
247 "userinfo_uri": "https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/userinfo",
248 "issuer": "https://iam.ebrains.eu/auth/realms/hbp"
249 }
250 }
messines 2.3 251
messines 3.1 252 {{/code}}