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 4.1
edited by fabricegaillard
on 2021/03/18 12:06
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.messines
1 +XWiki.fabricegaillard
Content
... ... @@ -1,2 +1,185 @@
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 +(% 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