Wiki source code of Community App Developer Guide

Version 4.3 by allan on 2019/09/19 18:31
Show last authors
1 Developers can extend the Collaboratory capabilities by providing applications to its community of users.
2
3 This guide describes the steps to make this possible.
4
5 {{toc numbered="true" start="2"/}}
6
7 == Becoming a contributor ==
8
9 The first step is for you to **become a contributor**. Contributors can register and manage applications within the Community Apps Catalogue.
10
11 Send an email to [[support@humanbrainproject.eu>>mailto:support@humanbrainproject.eu]] with a short summary of your intentions.
12
13 The support team will apply the permissions to your user: your account will be upgraded with developers privileges the next time you will login.
14
15 (% class="box infomessage" %)
16 (((
17 Only SGA2 accredited users will be automatically granted the contributor level.
18 )))
19
20 == Registering an application in the Catalogue ==
21
22 Collab authors find applications to add to their collabs in the Community Apps Catalogue.
23
24 {{error}}
25 TODO: describe the steps to register an app in the Catalogue
26 {{/error}}
27
28 == Creating your OpenID Connect client ==
29
30 The steps to create an OpenID Connect client are the following:
31
32 1. get an access token from the `developer` client
33 1. use the token to call the create endpoint
34 1. save your registration access token for further modifications of your client
35
36 === Fetching your developer access token ===
37
38 Getting your developer token is done in one simple step: authenticate against the developer client with the password grant.
39
40 This can be achieved with this sample shell script:
41
42 {{code language="bash"}}
43 # Gather username and password from user
44 echo '\nEnter your username' && read clb_dev_username &&
45 echo '\nEnter your password' && read -s clb_dev_pwd &&
46
47 # Fetch the token
48 curl -X POST https://iam.humanbrainproject.eu/auth/realms/hbp/protocol/openid-connect/token \
49 -u developer: \
50 -d 'grant_type=password' \
51 -d "username=${clb_dev_username}" \
52 -d "password=${clb_dev_pwd}" |
53
54 # Prettify the JSON response
55 json_pp;
56
57 # Erase the credentials from local variables
58 clb_dev_pwd='';clb_dev_username=''
59 {{/code}}
60
61 The response will be similar to:
62
63 {{code language="json"}}
64 {
65 "access_token": "eyJhbGci...",
66 "expires_in": 108000,
67 "refresh_expires_in": 14400,
68 "refresh_token": "eyJhbGci...",
69 "token_type": "bearer",
70 "not-before-policy": 1563261088,
71 "session_state": "0ac3dfcd-aa5e-42eb-b333-2f73496b81f8",
72 "scope": ""
73 }
74 {{/code}}
75
76 Copy the "access_token" value, you will need if for the next step.
77
78 === Creating the client ===
79
80 You can now create clients by sending a JSON representation to a specific endpoint:
81
82 {{code language="bash"}}
83 # Set your developer token
84 clb_dev_token=...
85
86 # Send the creation request
87 curl -X POST https://iam.humanbrainproject.eu/auth/realms/hbp/clients-registrations/default/ \
88 -H "Authorization: Bearer ${clb_dev_token}" \
89 -H 'Content-Type: application/json' \
90 -d '{
91 "clientId": "my-awesome-client",
92 "name": "My Awesome App",
93 "description": "This describes what my app is for end users",
94 "rootUrl": "https://root.url.of.my.app",
95 "baseUrl": "/relative/path/to/its/frontpage.html",
96 "redirectUris": [
97 "/relative/redirect/path",
98 "/these/can/use/wildcards/*"
99 ],
100 "webOrigins": ["+"],
101 "bearerOnly": false,
102 "consentRequired": true,
103 "standardFlowEnabled": true,
104 "implicitFlowEnabled": true,
105 "directAccessGrantsEnabled": false,
106 "attributes": {
107 "contacts": "first.contact@example.com; second.contact@example.com"
108 }
109 }' |
110
111 # Prettify the JSON response
112 json_pp;
113 {{/code}}
114
115 In case of success, the endpoint will return its representation of your client:
116
117 {{code language="json"}}
118 {
119 "defaultClientScopes" : [
120 "web-origins",
121 "roles"
122 ],
123 "redirectUris" : [
124 "/relative/redirect/path",
125 "/these/can/use/wildcards/*"
126 ],
127 "nodeReRegistrationTimeout" : -1,
128 "rootUrl" : "https://root.url.of.my.app",
129 "webOrigins" : [
130 "+"
131 ],
132 "authenticationFlowBindingOverrides" : {},
133 "baseUrl" : "/relative/path/to/its/frontpage.html",
134 "description" : "This describes what my app is for end users",
135 "notBefore" : 0,
136 "frontchannelLogout" : false,
137 "enabled" : true,
138 "registrationAccessToken" : "eyJhbGciOi...",
139 "consentRequired" : true,
140 "fullScopeAllowed" : false,
141 "clientAuthenticatorType" : "client-secret",
142 "surrogateAuthRequired" : false,
143 "directAccessGrantsEnabled" : false,
144 "standardFlowEnabled" : true,
145 "id" : "551b49a0-ec69-41af-9461-6c10fbc79a35",
146 "attributes" : {
147 "contacts" : "first.contact@example.com; second.contact@example.com"
148 },
149 "name" : "My Awesome App",
150 "secret" : "your-client-secret",
151 "publicClient" : false,
152 "clientId" : "my-awesome-client",
153 "optionalClientScopes" : [],
154 "implicitFlowEnabled" : true,
155 "protocol" : "openid-connect",
156 "bearerOnly" : false,
157 "serviceAccountsEnabled" : false
158 }
159 {{/code}}
160
161 Among all the attributes, you should securely save:
162
163 * your client **secret** ("secret" attribute): it is needed by your application to **authenticate to the IAM server** when making backend calls
164 * your client **registration access token** ("registrationAccessToken"): you will need it to authenticate when **modifying your client in the future**
165
166 === Modifying your client ===
167
168 Update your client with a PUT request:
169
170 {{code language="bash"}}
171 # Set your registration token and client id
172 clb_reg_token=...
173
174 # Update the client
175 curl -X PUT https://iam.humanbrainproject.eu/auth/realms/hbp/clients-registrations/default/my-awesome-client \
176 -H "Authorization: Bearer ${clb_reg_token}" \
177 -H 'Content-Type: application/json' \
178 -d '{
179 "clientId": "my-awesome-client",
180 "redirectUris": [
181 "/relative/redirect/path",
182 "/these/can/use/wildcards/*",
183 "/a/new/redirect/uri"
184 ]
185 }' |
186
187 # Prettify the JSON response
188 json_pp;
189 {{/code}}
190
191 Note that your need to provide your client id both in the endpoint URL and within the body of the request.
192
193 {{warning}}
194 /!\ ** 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.   **/!\
195 {{/warning}}