Wiki source code of Community App Developer Guide

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