Last modified by bougault on 2022/03/02 11:58
From version 5.1
edited by allan
on 2019/11/21 16:10
Change comment: There is no comment for this version
To version 2.1
edited by allan
on 2019/09/18 15:51
Change comment: Fetching your developer access token

Summary

Details

Page properties
Content
... ... @@ -1,25 +1,25 @@
1 -Developers can extend the Collaboratory capabilities by providing applications to its community of users.
1 +The Collaboratory is designed to be extended with applications provided by its community of users.
2 2  
3 -This guide describes the steps to make this possible.
3 +This guide describes how developers can contribute by creating and registering applications within the Collaboratory.
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 **become a contributor**. Contributors can register and manage applications within the Community Apps Catalogue.
9 +The first step is for you to be recognised as a contributor. Contributors can register and manage applications within the Community Apps Catalogue.
10 10  
11 -Send an email to [[support@humanbrainproject.eu>>mailto:support@humanbrainproject.eu]] with a short summary of your intentions.
11 +To become a contributor, 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: your account will be upgraded with developers privileges the next time you will login.
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.
14 14  
15 15  (% class="box infomessage" %)
16 16  (((
17 -Only SGA2 accredited users will be automatically granted the contributor level.
17 +Please note that, currently, 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 -Collab authors find applications to add to their collabs in the Community Apps Catalogue.
22 +The Community Apps Catalogue is the place where collab authors look for applications to add to their collabs.
23 23  
24 24  {{error}}
25 25  TODO: describe the steps to register an app in the Catalogue
... ... @@ -29,20 +29,20 @@
29 29  
30 30  The steps to create an OpenID Connect client are the following:
31 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
32 +* get an access token from the `developer` client
33 +* use the token to call the create endpoint
34 +* save your registration access token for further modify your client
35 35  
36 36  === Fetching your developer access token ===
37 37  
38 -Getting your developer token is done in one simple step: authenticate against the developer client with the password grant.
38 +In order to get your developer token, you need to authenticate against the developer client with the password grant.
39 39  
40 -This can be achieved with this sample shell script:
40 +This can be achieved with this sample bash script:
41 41  
42 42  {{code language="bash"}}
43 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 &&
44 +echo 'Enter your username' && read clb_dev_username &&
45 +echo 'Enter your password' && read -s clb_dev_pwd &&
46 46  
47 47  # Fetch the token
48 48  curl -X POST https://iam.humanbrainproject.eu/auth/realms/hbp/protocol/openid-connect/token \
... ... @@ -49,10 +49,7 @@
49 49   -u developer: \
50 50   -d 'grant_type=password' \
51 51   -d "username=${clb_dev_username}" \
52 - -d "password=${clb_dev_pwd}" |
53 -
54 -# Prettify the JSON response
55 -json_pp;
52 + -d "password=${clb_dev_pwd}"; \
56 56  
57 57  # Erase the credentials from local variables
58 58  clb_dev_pwd='';clb_dev_username=''
... ... @@ -73,123 +73,4 @@
73 73  }
74 74  {{/code}}
75 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}}
73 +Copy the "access_token" value, it is the one that will be needed for the next step.
XWiki.DocumentSheetBinding[0]