Wiki source code of 1. Registering an OIDC client

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