Last modified by bougault on 2022/03/02 11:58
From version 29.1
edited by mmorgan
on 2020/06/19 16:22
Change comment: Renamed back-links.
To version 22.1
edited by allan
on 2020/02/26 14:26
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.mmorgan
1 +XWiki.allan
Content
... ... @@ -6,7 +6,7 @@
6 6  
7 7  The first step is for you to **get the developer accreditation**. Contributors can register and manage applications within the Community Apps Catalogue.
8 8  
9 -Send an email to [[support@ebrains.eu>>mailto:support@ebrains.eu]] with a short summary of your intentions.
9 +Send an email to [[support@humanbrainproject.eu>>mailto:support@humanbrainproject.eu]] with a short summary of your intentions.
10 10  
11 11  The support team will apply the permissions to your user: your account will be [[upgraded with developers privileges>>doc:Collabs.collab-devs.collaboratory-v2.keycloak.user administration.WebHome]] the next time you will login.
12 12  
... ... @@ -21,8 +21,6 @@
21 21  
22 22  Once this simple step is complete, users will be able to install your app within their collabs.
23 23  
24 -If you are dealing with private data, or your users need to be authenticated, see [[authentication and authorisation in the Collaboratory.>>doc:Collabs.the-collaboratory.Technical documentation.Architecture.Permissions.Authentication & Authorisation using OIDC.WebHome]]
25 -
26 26  === Registering an application in the Catalogue ===
27 27  
28 28  Navigate to the catalogue and click on **+Create App** in the top right corner. Enter a name for your app and click on **Create**.
... ... @@ -76,7 +76,7 @@
76 76   setting2: 'setting 2 value',
77 77   // ...
78 78   // reload: false // avoid page reload on settings change
79 - }}, 'https://wiki.ebrains.eu');
77 + }}, 'https://wiki.humanbrainproject.eu');
80 80  {{/code}}
81 81  
82 82  === Fetching settings ===
... ... @@ -85,4 +85,169 @@
85 85  
86 86  == Creating your OpenID Connect client ==
87 87  
88 -See the instructions [[here>>doc:.Registering an OIDC client.WebHome]].
86 +The steps to create an OpenID Connect client are the following:
87 +
88 +1. get an access token from the `developer` client
89 +1. use the token to call the create endpoint
90 +1. save your registration access token for further modifications of your client
91 +
92 +=== Fetching your developer access token ===
93 +
94 +Getting your developer token is done in one simple step: authenticate against the developer client with the password grant.
95 +
96 +This can be achieved with this sample shell script:
97 +
98 +{{code language="bash"}}
99 +# Gather username and password from user
100 +echo '\nEnter your username' && read clb_dev_username &&
101 +echo '\nEnter your password' && read -s clb_dev_pwd &&
102 +
103 +# Fetch the token
104 +curl -X POST https://iam.humanbrainproject.eu/auth/realms/hbp/protocol/openid-connect/token \
105 + -u developer: \
106 + -d 'grant_type=password' \
107 + --data-urlencode "username=${clb_dev_username}" \
108 + --data-urlencode "password=${clb_dev_pwd}" |
109 +
110 +# Prettify the JSON response
111 +json_pp;
112 +
113 +# Erase the credentials from local variables
114 +clb_dev_pwd='';clb_dev_username=''
115 +{{/code}}
116 +
117 +The response will be similar to:
118 +
119 +{{code language="json"}}
120 +{
121 + "access_token": "eyJhbGci...",
122 + "expires_in": 108000,
123 + "refresh_expires_in": 14400,
124 + "refresh_token": "eyJhbGci...",
125 + "token_type": "bearer",
126 + "not-before-policy": 1563261088,
127 + "session_state": "0ac3dfcd-aa5e-42eb-b333-2f73496b81f8",
128 + "scope": ""
129 +}
130 +{{/code}}
131 +
132 +Copy the "access_token" value, you will need if for the next step.
133 +
134 +=== Creating the client ===
135 +
136 +You can now create clients by sending a JSON representation to a specific endpoint:
137 +
138 +{{code language="bash"}}
139 +# Set your developer token
140 +clb_dev_token=...
141 +
142 +# Send the creation request
143 +curl -X POST https://iam.humanbrainproject.eu/auth/realms/hbp/clients-registrations/default/ \
144 + -H "Authorization: Bearer ${clb_dev_token}" \
145 + -H 'Content-Type: application/json' \
146 + -d '{
147 + "clientId": "my-awesome-client",
148 + "name": "My Awesome App",
149 + "description": "This describes what my app is for end users",
150 + "rootUrl": "https://root.url.of.my.app",
151 + "baseUrl": "/relative/path/to/its/frontpage.html",
152 + "redirectUris": [
153 + "/relative/redirect/path",
154 + "/these/can/use/wildcards/*"
155 + ],
156 + "webOrigins": ["+"],
157 + "bearerOnly": false,
158 + "consentRequired": true,
159 + "standardFlowEnabled": true,
160 + "implicitFlowEnabled": true,
161 + "directAccessGrantsEnabled": false,
162 + "attributes": {
163 + "contacts": "first.contact@example.com; second.contact@example.com"
164 + }
165 + }' |
166 +
167 +# Prettify the JSON response
168 +json_pp;
169 +{{/code}}
170 +
171 +In case of success, the endpoint will return its representation of your client:
172 +
173 +{{code language="json"}}
174 +{
175 + "defaultClientScopes" : [
176 + "web-origins",
177 + "roles"
178 + ],
179 + "redirectUris" : [
180 + "/relative/redirect/path",
181 + "/these/can/use/wildcards/*"
182 + ],
183 + "nodeReRegistrationTimeout" : -1,
184 + "rootUrl" : "https://root.url.of.my.app",
185 + "webOrigins" : [
186 + "+"
187 + ],
188 + "authenticationFlowBindingOverrides" : {},
189 + "baseUrl" : "/relative/path/to/its/frontpage.html",
190 + "description" : "This describes what my app is for end users",
191 + "notBefore" : 0,
192 + "frontchannelLogout" : false,
193 + "enabled" : true,
194 + "registrationAccessToken" : "eyJhbGciOi...",
195 + "consentRequired" : true,
196 + "fullScopeAllowed" : false,
197 + "clientAuthenticatorType" : "client-secret",
198 + "surrogateAuthRequired" : false,
199 + "directAccessGrantsEnabled" : false,
200 + "standardFlowEnabled" : true,
201 + "id" : "551b49a0-ec69-41af-9461-6c10fbc79a35",
202 + "attributes" : {
203 + "contacts" : "first.contact@example.com; second.contact@example.com"
204 + },
205 + "name" : "My Awesome App",
206 + "secret" : "your-client-secret",
207 + "publicClient" : false,
208 + "clientId" : "my-awesome-client",
209 + "optionalClientScopes" : [],
210 + "implicitFlowEnabled" : true,
211 + "protocol" : "openid-connect",
212 + "bearerOnly" : false,
213 + "serviceAccountsEnabled" : false
214 +}
215 +{{/code}}
216 +
217 +Among all the attributes, you should securely save:
218 +
219 +* your client **secret** ("secret" attribute): it is needed by your application to **authenticate to the IAM server** when making backend calls
220 +* your client **registration access token** ("registrationAccessToken"): you will need it to authenticate when **modifying your client in the future**
221 +
222 +=== Modifying your client ===
223 +
224 +Update your client with a PUT request:
225 +
226 +{{code language="bash"}}
227 +# Set your registration token and client id
228 +clb_reg_token=...
229 +
230 +# Update the client
231 +curl -X PUT https://iam.humanbrainproject.eu/auth/realms/hbp/clients-registrations/default/my-awesome-client \
232 + -H "Authorization: Bearer ${clb_reg_token}" \
233 + -H 'Content-Type: application/json' \
234 + -d '{
235 + "clientId": "my-awesome-client",
236 + "redirectUris": [
237 + "/relative/redirect/path",
238 + "/these/can/use/wildcards/*",
239 + "/a/new/redirect/uri"
240 + ]
241 + }' |
242 +
243 +# Prettify the JSON response
244 +json_pp;
245 +{{/code}}
246 +
247 + Note that your need to provide your client id both in the endpoint URL and within the body of the request.
248 +
249 +{{warning}}
250 +/!\ ** Each time you modify your client, a new registration access token will be generated. You need to track of your token changes to keep access to your client. **/!\
251 +{{/warning}}