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

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.allan
1 +XWiki.mmorgan
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@humanbrainproject.eu>>mailto:support@humanbrainproject.eu]] with a short summary of your intentions.
9 +Send an email to [[support@ebrains.eu>>mailto:support@ebrains.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,6 +21,8 @@
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 +
24 24  === Registering an application in the Catalogue ===
25 25  
26 26  Navigate to the catalogue and click on **+Create App** in the top right corner. Enter a name for your app and click on **Create**.
... ... @@ -74,7 +74,7 @@
74 74   setting2: 'setting 2 value',
75 75   // ...
76 76   // reload: false // avoid page reload on settings change
77 - }}, 'https://wiki.humanbrainproject.eu');
79 + }}, 'https://wiki.ebrains.eu');
78 78  {{/code}}
79 79  
80 80  === Fetching settings ===
... ... @@ -83,169 +83,4 @@
83 83  
84 84  == Creating your OpenID Connect client ==
85 85  
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}}
88 +See the instructions [[here>>doc:.Registering an OIDC client.WebHome]].