Last modified by messines on 2022/05/25 10:11
From version 11.1
edited by messines
on 2022/05/25 10:11
Change comment: There is no comment for this version
To version 2.1
edited by mmorgan
on 2020/07/16 01:43
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -1. Registering an OIDC client
1 +Registering an OIDC client
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.messines
1 +XWiki.mmorgan
Content
... ... @@ -1,2 +1,174 @@
1 -Please find the new documentation here
2 -\\[[https:~~/~~/wiki.ebrains.eu/bin/view/Collabs/the-collaboratory/Documentation%20IAM/FAQ/OIDC%20Clients%20explained/1.%20Registering%20an%20OIDC%20client%20v2/>>https://wiki.ebrains.eu/bin/view/Collabs/the-collaboratory/Documentation%20IAM/FAQ/OIDC%20Clients%20explained/1.%20Registering%20an%20OIDC%20client%20v2/]]
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=...
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}}
173 +
174 +
Table of content