Last modified by bougault on 2022/03/02 11:58
From version 1.1
edited by allan
on 2019/09/12 16:08
Change comment: There is no comment for this version
To version 5.1
edited by allan
on 2019/11/21 16:10
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,22 +1,195 @@
1 -The Collaboratory is designed to be extended with applications provided by its community of users.
1 +Developers can extend the Collaboratory capabilities by providing applications to its community of users.
2 2  
3 -This guide describes how developers can contribute by creating and registering applications within the Collaboratory.
3 +This guide describes the steps to make this possible.
4 4  
5 5  {{toc numbered="true" start="2"/}}
6 6  
7 7  == Becoming a contributor ==
8 8  
9 -The first step is for you to be recognised as a contributor. Contributors can register and manage applications within the Community Apps Catalogue.
9 +The first step is for you to **become a contributor**. Contributors can register and manage applications within the Community Apps Catalogue.
10 10  
11 -To become a contributor, send an email to [[support@humanbrainproject.eu>>mailto:support@humanbrainproject.eu]] with a short summary of your intentions.
11 +Send an email to [[support@humanbrainproject.eu>>mailto:support@humanbrainproject.eu]] with a short summary of your intentions.
12 12  
13 -The support team will apply the permissions to your user and the next time you will login, your account will be upgraded with developers privileges.
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 14  
15 15  (% class="box infomessage" %)
16 16  (((
17 -Please note that, currently, only SGA2 accredited users will be automatically granted the contributor level.
17 +Only SGA2 accredited users will be automatically granted the contributor level.
18 18  )))
19 19  
20 20  == Registering an application in the Catalogue ==
21 21  
22 -The Community Apps Catalogue is the place where collab authors look for applications to add to their collabs.
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}}
XWiki.DocumentSheetBinding[0]