Wiki source code of 1. Registering an OIDC client

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