Wiki source code of 1. Registering an OIDC client

Version 10.1 by messines on 2021/11/15 14:39
Show last authors
1 == Must read before starting ==
2
3 It's very important to choose the right type of clients and to understand the various OAuth flows.
4
5 A very good documentation is this one :
6
7 [[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]]
8
9 and another one
10
11 [[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]]
12
13 == Creating your OpenID Connect client ==
14
15 The steps to create an OpenID Connect (OIDC) client are the following:
16
17 1. Ask the developer accreditation to be authorize to create client
18 1. get an access token from the `developer` client
19 1. save your registration access token for further modifications of your client
20 1. use the token to call the create endpoint
21
22 ==== Easiest way to create a client ====
23
24 **A live exemple of client ID creation is available here on our lab**, you can perfectly use this notebook to create your client, the next steps in this documentation reproduce the content of the notebook. **The easiest solution as a user is to use this notebook to create a client** and avoid human error while executing curl request manually.
25
26 [[https:~~/~~/lab.ebrains.eu/user/user-redirect/lab/tree/shared/Collaboratory%20Community%20Apps/Managing%20an%20OpenID%20Connect%20client.ipynb>>https://lab.ebrains.eu/user/user-redirect/lab/tree/shared/Collaboratory%20Community%20Apps/Managing%20an%20OpenID%20Connect%20client.ipynb]]
27
28 === Ask for developer accreditation ===
29
30 To be authorize to create an OIDC client you have to be accredited as developer.
31
32 Please go on this page and "Request to join" the group [[https:~~/~~/wiki.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam~~-~~-service-providers>>https://wiki.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam--service-providers]]
33
34 We will quickly process your request and you will be able to create an OIDC client
35
36 === Fetching your developer access token ===
37
38 Getting your developer token is done in one simple step: authenticate against the developer client with the password grant.
39
40 This can be achieved with this sample shell script:
41
42 {{code language="bash"}}
43 # Gather username and password from user
44 read -p 'Enter your username: ' clb_dev_username
45 read -s -p 'Enter your password: ' clb_dev_pwd
46
47 # Fetch the token
48 curl -X POST https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token \
49 -u developer: \
50 -d 'grant_type=password' \
51 --data-urlencode "username=${clb_dev_username}" \
52 --data-urlencode "password=${clb_dev_pwd}" |
53
54 # and pretty-print the JSON response
55 json_pp
56
57 # Erase the credentials from local variables
58 clb_dev_pwd=''; clb_dev_username=''
59 {{/code}}
60
61 The response will be similar to:
62
63 {{code language="json"}}
64 {
65 "access_token": "eyJhbGci...",
66 "expires_in": 108000,
67 "refresh_expires_in": 14400,
68 "refresh_token": "eyJhbGci...",
69 "token_type": "bearer",
70 "not-before-policy": 1563261088,
71 "session_state": "0ac3dfcd-aa5e-42eb-b333-2f73496b81f8",
72 "scope": ""
73 }
74 {{/code}}
75
76 Store a copy of the "access_token" value. You will need if for the next step.
77
78 === Creating the client ===
79
80 You can now create clients by sending a JSON representation to a specific endpoint:
81
82 {{code language="bash"}}
83 # Set your developer token
84 clb_dev_token="eyJhbGci..."
85
86 # Send the creation request
87 curl -X POST https://iam.ebrains.eu/auth/realms/hbp/clients-registrations/default/ \
88 -H "Authorization: Bearer ${clb_dev_token}" \
89 -H 'Content-Type: application/json' \
90 -d '{ "clientId": "your_client_id",
91 "name": "Collaboratory workshop demo client edited",
92 "description": "This describes what my app is for end users",
93 "rootUrl": "https://example.org",
94 "baseUrl": "https://example.org",
95 "redirectUris": [
96 "/login/*",
97 "https://example.org/login/*"
98 ],
99 "webOrigins":["http://localhost:8080","https://example.org","+"],
100 "bearerOnly": False,
101 "consentRequired": True,
102 "standardFlowEnabled": True,
103 "implicitFlowEnabled": False,
104 "directAccessGrantsEnabled": False,
105 "attributes": {
106 "contacts": "first.contact@example.com; second.contact@example.com"
107 },
108 "defaultClientScopes": ["openid","profile","email","roles"],
109 "optionalClientScopes": ["team","group"]
110 }' |
111
112 # Pretty print the JSON response
113 json_pp;
114 {{/code}}
115
116 In case of success, the endpoint will return its representation of your client:
117
118 {{code language="json"}}
119 {
120 "defaultClientScopes" : [
121 "web-origins",
122 "roles"
123 ],
124 "redirectUris" : [
125 "/relative/redirect/path",
126 "/these/can/use/wildcards/*"
127 ],
128 "nodeReRegistrationTimeout" : -1,
129 "rootUrl" : "https://root.url.of.my.app",
130 "webOrigins" : [
131 "+"
132 ],
133 "authenticationFlowBindingOverrides" : {},
134 "baseUrl" : "/relative/path/to/its/frontpage.html",
135 "description" : "This describes what my app is for end users",
136 "notBefore" : 0,
137 "frontchannelLogout" : false,
138 "enabled" : true,
139 "registrationAccessToken" : "eyJhbGciOi...",
140 "consentRequired" : true,
141 "fullScopeAllowed" : false,
142 "clientAuthenticatorType" : "client-secret",
143 "surrogateAuthRequired" : false,
144 "directAccessGrantsEnabled" : false,
145 "standardFlowEnabled" : true,
146 "id" : "551b49a0-ec69-41af-9461-6c10fbc79a35",
147 "attributes" : {
148 "contacts" : "first.contact@example.com; second.contact@example.com"
149 },
150 "name" : "My Awesome App",
151 "secret" : "your-client-secret",
152 "publicClient" : false,
153 "clientId" : "my-awesome-client",
154 "optionalClientScopes" : [],
155 "implicitFlowEnabled" : true,
156 "protocol" : "openid-connect",
157 "bearerOnly" : false,
158 "serviceAccountsEnabled" : false
159 }
160 {{/code}}
161
162 Among all the attributes, you should securely save:
163
164 * your client **secret** ("secret" attribute): it is needed by your application to **authenticate to the IAM server** when making back-end calls
165 * your client **registration access token** ("registrationAccessToken"): you will need it to authenticate when **modifying your client in the future**
166
167 === Modifying your client ===
168
169 Update your client with a PUT request:
170
171 {{code language="bash"}}
172 # Set your registration token and client id
173 clb_reg_token="eyJhbGciOi..."
174 clb_client_id="my-awesome-client"
175
176 # Update the client. Note that the client ID appears both in the endpoint URL and in the body of the request.
177 curl -X PUT https://iam.ebrains.eu/auth/realms/hbp/clients-registrations/default/${clb_client_id} \
178 -H "Authorization: Bearer ${clb_reg_token}" \
179 -H 'Content-Type: application/json' \
180 -d '{
181 "clientId": "'${clb_client_id}'",
182 "redirectUris": [
183 "/relative/redirect/path",
184 "/these/can/use/wildcards/*",
185 "/a/new/redirect/uri"
186 ]
187 }' |
188
189 # Pretty print the JSON response
190 json_pp
191
192 {{/code}}
193
194 Note that your need to provide your client id both in the endpoint URL and within the body of the request.
195
196 {{warning}}
197 **⚠  Each time you modify your client, a new registration access token is generated. You need to keep track of your latest token to keep access to your client.  ⚠**
198 {{/warning}}
Table of content