Last modified by bougault on 2022/03/02 11:58
From version 26.1
edited by allan
on 2020/03/10 13:46
Change comment: There is no comment for this version
To version 28.1
edited by villemai
on 2020/05/04 16:32
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.allan
1 +XWiki.villemai
Content
... ... @@ -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.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**.
... ... @@ -83,171 +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 -Note that a [[notebook>>https://lab.ebrains.eu/user-redirect/lab/tree/drive/Shared%20with%20all/Collaboratory%20Community%20Apps/Managing%20an%20OpenID%20Connect%20client.ipynb||rel="noopener noreferrer" target="_blank"]] is available to help you create and modify your OIDC client.
93 -
94 -=== Fetching your developer access token ===
95 -
96 -Getting your developer token is done in one simple step: authenticate against the developer client with the password grant.
97 -
98 -This can be achieved with this sample shell script:
99 -
100 -{{code language="bash"}}
101 -# Gather username and password from user
102 -echo '\nEnter your username' && read clb_dev_username &&
103 -echo '\nEnter your password' && read -s clb_dev_pwd &&
104 -
105 -# Fetch the token
106 -curl -X POST https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token \
107 - -u developer: \
108 - -d 'grant_type=password' \
109 - --data-urlencode "username=${clb_dev_username}" \
110 - --data-urlencode "password=${clb_dev_pwd}" |
111 -
112 -# Prettify the JSON response
113 -json_pp;
114 -
115 -# Erase the credentials from local variables
116 -clb_dev_pwd='';clb_dev_username=''
117 -{{/code}}
118 -
119 -The response will be similar to:
120 -
121 -{{code language="json"}}
122 -{
123 - "access_token": "eyJhbGci...",
124 - "expires_in": 108000,
125 - "refresh_expires_in": 14400,
126 - "refresh_token": "eyJhbGci...",
127 - "token_type": "bearer",
128 - "not-before-policy": 1563261088,
129 - "session_state": "0ac3dfcd-aa5e-42eb-b333-2f73496b81f8",
130 - "scope": ""
131 -}
132 -{{/code}}
133 -
134 -Copy the "access_token" value, you will need if for the next step.
135 -
136 -=== Creating the client ===
137 -
138 -You can now create clients by sending a JSON representation to a specific endpoint:
139 -
140 -{{code language="bash"}}
141 -# Set your developer token
142 -clb_dev_token=...
143 -
144 -# Send the creation request
145 -curl -X POST https://iam.ebrains.eu/auth/realms/hbp/clients-registrations/default/ \
146 - -H "Authorization: Bearer ${clb_dev_token}" \
147 - -H 'Content-Type: application/json' \
148 - -d '{
149 - "clientId": "my-awesome-client",
150 - "name": "My Awesome App",
151 - "description": "This describes what my app is for end users",
152 - "rootUrl": "https://root.url.of.my.app",
153 - "baseUrl": "/relative/path/to/its/frontpage.html",
154 - "redirectUris": [
155 - "/relative/redirect/path",
156 - "/these/can/use/wildcards/*"
157 - ],
158 - "webOrigins": ["+"],
159 - "bearerOnly": false,
160 - "consentRequired": true,
161 - "standardFlowEnabled": true,
162 - "implicitFlowEnabled": true,
163 - "directAccessGrantsEnabled": false,
164 - "attributes": {
165 - "contacts": "first.contact@example.com; second.contact@example.com"
166 - }
167 - }' |
168 -
169 -# Prettify the JSON response
170 -json_pp;
171 -{{/code}}
172 -
173 -In case of success, the endpoint will return its representation of your client:
174 -
175 -{{code language="json"}}
176 -{
177 - "defaultClientScopes" : [
178 - "web-origins",
179 - "roles"
180 - ],
181 - "redirectUris" : [
182 - "/relative/redirect/path",
183 - "/these/can/use/wildcards/*"
184 - ],
185 - "nodeReRegistrationTimeout" : -1,
186 - "rootUrl" : "https://root.url.of.my.app",
187 - "webOrigins" : [
188 - "+"
189 - ],
190 - "authenticationFlowBindingOverrides" : {},
191 - "baseUrl" : "/relative/path/to/its/frontpage.html",
192 - "description" : "This describes what my app is for end users",
193 - "notBefore" : 0,
194 - "frontchannelLogout" : false,
195 - "enabled" : true,
196 - "registrationAccessToken" : "eyJhbGciOi...",
197 - "consentRequired" : true,
198 - "fullScopeAllowed" : false,
199 - "clientAuthenticatorType" : "client-secret",
200 - "surrogateAuthRequired" : false,
201 - "directAccessGrantsEnabled" : false,
202 - "standardFlowEnabled" : true,
203 - "id" : "551b49a0-ec69-41af-9461-6c10fbc79a35",
204 - "attributes" : {
205 - "contacts" : "first.contact@example.com; second.contact@example.com"
206 - },
207 - "name" : "My Awesome App",
208 - "secret" : "your-client-secret",
209 - "publicClient" : false,
210 - "clientId" : "my-awesome-client",
211 - "optionalClientScopes" : [],
212 - "implicitFlowEnabled" : true,
213 - "protocol" : "openid-connect",
214 - "bearerOnly" : false,
215 - "serviceAccountsEnabled" : false
216 -}
217 -{{/code}}
218 -
219 -Among all the attributes, you should securely save:
220 -
221 -* your client **secret** ("secret" attribute): it is needed by your application to **authenticate to the IAM server** when making backend calls
222 -* your client **registration access token** ("registrationAccessToken"): you will need it to authenticate when **modifying your client in the future**
223 -
224 -=== Modifying your client ===
225 -
226 -Update your client with a PUT request:
227 -
228 -{{code language="bash"}}
229 -# Set your registration token and client id
230 -clb_reg_token=...
231 -
232 -# Update the client
233 -curl -X PUT https://iam.ebrains.eu/auth/realms/hbp/clients-registrations/default/my-awesome-client \
234 - -H "Authorization: Bearer ${clb_reg_token}" \
235 - -H 'Content-Type: application/json' \
236 - -d '{
237 - "clientId": "my-awesome-client",
238 - "redirectUris": [
239 - "/relative/redirect/path",
240 - "/these/can/use/wildcards/*",
241 - "/a/new/redirect/uri"
242 - ]
243 - }' |
244 -
245 -# Prettify the JSON response
246 -json_pp;
247 -{{/code}}
248 -
249 - Note that your need to provide your client id both in the endpoint URL and within the body of the request.
250 -
251 -{{warning}}
252 -/!\ ** Each time you modify your client, a new registration access token will be generated. You need to keep track of your token changes to keep access to your client.   **/!\
253 -{{/warning}}
88 +See the instructions [[here>>doc:.Registering an OIDC client.WebHome]].