Changes for page Community App Developer Guide

Last modified by bougault on 2022/03/02 11:58

From 7.1 to 8.1

From version 1.1

edited by allan
on 2019/09/12 16:08

Change comment: There is no comment for this version

To version 7.1

edited by allan
on 2019/11/21 16:14

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)
Objects (0 modified, 2 added, 0 removed)
- XWiki.DocumentSheetBinding[0]
- XWiki.DocumentSheetBinding[1]

Details

Page properties

Content

@@ -1,22 +1,195 @@
--The Collaboratory is designed to be extended with applications provided by its community of users.
++Developers can extend the Collaboratory capabilities by providing applications to its community of users.
--This guide describes how developers can contribute by creating and registering applications within the Collaboratory.
++This guide describes the steps to make this possible.
  {{toc numbered="true" start="2"/}}
  == Becoming a contributor ==
--The first step is for you to be recognised as a contributor. Contributors can register and manage applications within the Community Apps Catalogue.
++The first step is for you to **become a contributor**. Contributors can register and manage applications within the Community Apps Catalogue.
--To become a contributor, send an email to [[support@humanbrainproject.eu>>mailto:support@humanbrainproject.eu]] with a short summary of your intentions.
++Send an email to [[support@humanbrainproject.eu>>mailto:support@humanbrainproject.eu]] with a short summary of your intentions.
--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.
++The support team will apply the permissions to your user: your account will be upgraded with developers privileges the next time you will login.
  (% class="box infomessage" %)
  (((
--Please note that, currently, only SGA2 accredited users will be automatically granted the contributor level.
++Only SGA2 accredited users will be automatically granted the contributor level.
  )))
  == Registering an application in the Catalogue ==
--The Community Apps Catalogue is the place where collab authors look for applications to add to their collabs.
++Collab authors find applications to add to their collabs in the Community Apps Catalogue.
++
++{{error}}
++TODO: describe the steps to register an app in the Catalogue
++{{/error}}
++
++== Creating your OpenID Connect client ==
++
++The steps to create an OpenID Connect client are the following:
++
++1. get an access token from the `developer` client
++1. use the token to call the create endpoint
++1. save your registration access token for further modifications of your client
++
++=== Fetching your developer access token ===
++
++Getting your developer token is done in one simple step: authenticate against the developer client with the password grant.
++
++This can be achieved with this sample shell script:
++
++{{code language="bash"}}
++# Gather username and password from user
++echo '\nEnter your username' && read clb_dev_username &&
++echo '\nEnter your password' && read -s clb_dev_pwd &&
++
++# Fetch the token
++curl -X POST https://iam.humanbrainproject.eu/auth/realms/hbp/protocol/openid-connect/token \
++  -u developer: \
++  -d 'grant_type=password' \
++  -d "username=${clb_dev_username}" \
++  -d "password=${clb_dev_pwd}" |
++
++# Prettify the JSON response
++json_pp;
++
++# Erase the credentials from local variables
++clb_dev_pwd='';clb_dev_username=''
++{{/code}}
++
++The response will be similar to:
++
++{{code language="json"}}
++{
++    "access_token": "eyJhbGci...",
++    "expires_in": 108000,
++    "refresh_expires_in": 14400,
++    "refresh_token": "eyJhbGci...",
++    "token_type": "bearer",
++    "not-before-policy": 1563261088,
++    "session_state": "0ac3dfcd-aa5e-42eb-b333-2f73496b81f8",
++    "scope": ""
++}
++{{/code}}
++
++Copy the "access_token" value, you will need if for the next step.
++
++=== Creating the client ===
++
++You can now create clients by sending a JSON representation to a specific endpoint:
++
++{{code language="bash"}}
++# Set your developer token
++clb_dev_token=...
++
++# Send the creation request
++curl -X POST https://iam.humanbrainproject.eu/auth/realms/hbp/clients-registrations/default/ \
++  -H "Authorization: Bearer ${clb_dev_token}" \
++  -H 'Content-Type: application/json' \
++  -d '{
++        "clientId": "my-awesome-client",
++        "name": "My Awesome App",
++        "description": "This describes what my app is for end users",
++        "rootUrl": "https://root.url.of.my.app",
++        "baseUrl": "/relative/path/to/its/frontpage.html",
++        "redirectUris": [
++            "/relative/redirect/path",
++            "/these/can/use/wildcards/*"
++        ],
++        "webOrigins": ["+"],
++        "bearerOnly": false,
++        "consentRequired": true,
++        "standardFlowEnabled": true,
++        "implicitFlowEnabled": true,
++        "directAccessGrantsEnabled": false,
++        "attributes": {
++            "contacts": "first.contact@example.com; second.contact@example.com"
++        }
++    }' |
++
++# Prettify the JSON response
++json_pp;
++{{/code}}
++
++In case of success, the endpoint will return its representation of your client:
++
++{{code language="json"}}
++{
++   "defaultClientScopes" : [
++      "web-origins",
++      "roles"
++   ],
++   "redirectUris" : [
++      "/relative/redirect/path",
++      "/these/can/use/wildcards/*"
++   ],
++   "nodeReRegistrationTimeout" : -1,
++   "rootUrl" : "https://root.url.of.my.app",
++   "webOrigins" : [
++      "+"
++   ],
++   "authenticationFlowBindingOverrides" : {},
++   "baseUrl" : "/relative/path/to/its/frontpage.html",
++   "description" : "This describes what my app is for end users",
++   "notBefore" : 0,
++   "frontchannelLogout" : false,
++   "enabled" : true,
++   "registrationAccessToken" : "eyJhbGciOi...",
++   "consentRequired" : true,
++   "fullScopeAllowed" : false,
++   "clientAuthenticatorType" : "client-secret",
++   "surrogateAuthRequired" : false,
++   "directAccessGrantsEnabled" : false,
++   "standardFlowEnabled" : true,
++   "id" : "551b49a0-ec69-41af-9461-6c10fbc79a35",
++   "attributes" : {
++      "contacts" : "first.contact@example.com; second.contact@example.com"
++   },
++   "name" : "My Awesome App",
++   "secret" : "your-client-secret",
++   "publicClient" : false,
++   "clientId" : "my-awesome-client",
++   "optionalClientScopes" : [],
++   "implicitFlowEnabled" : true,
++   "protocol" : "openid-connect",
++   "bearerOnly" : false,
++   "serviceAccountsEnabled" : false
++}
++{{/code}}
++
++Among all the attributes, you should securely save:
++
++* your client **secret** ("secret" attribute): it is needed by your application to **authenticate to the IAM server** when making backend calls
++* your client **registration access token** ("registrationAccessToken"): you will need it to authenticate when **modifying your client in the future**
++
++=== Modifying your client ===
++
++Update your client with a PUT request:
++
++{{code language="bash"}}
++# Set your registration token and client id
++clb_reg_token=...
++
++# Update the client
++curl -X PUT https://iam.humanbrainproject.eu/auth/realms/hbp/clients-registrations/default/my-awesome-client \
++  -H "Authorization: Bearer ${clb_reg_token}" \
++  -H 'Content-Type: application/json' \
++  -d '{
++        "clientId": "my-awesome-client",
++        "redirectUris": [
++            "/relative/redirect/path",
++            "/these/can/use/wildcards/*",
++            "/a/new/redirect/uri"
++        ]
++    }' |
++
++# Prettify the JSON response
++json_pp;
++{{/code}}
++
++ Note that your need to provide your client id both in the endpoint URL and within the body of the request.
++
++{{warning}}
++/!\ **  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.   **/!\
++{{/warning}}