Wiki source code of Registering an OIDC client

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