Community App Developer Guide

Version 2.1 by allan on 2019/09/18 15:51

The Collaboratory is designed to be extended with applications provided by its community of users.

This guide describes how developers can contribute by creating and registering applications within the Collaboratory.

  1. Becoming a contributor
  2. Registering an application in the Catalogue
  3. Creating your OpenID Connect client
    1. Fetching your developer access token

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.

To become a contributor, send an email to 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.

Please note that, currently, 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.

TODO: describe the steps to register an app in the Catalogue

Creating your OpenID Connect client

The steps to create an OpenID Connect client are the following:

  • get an access token from the `developer` client
  • use the token to call the create endpoint
  • save your registration access token for further modify your client

Fetching your developer access token

In order to get your developer token, you need to authenticate against the developer client with the password grant.

This can be achieved with this sample bash script:

# Gather username and password from user
echo 'Enter your username' && read clb_dev_username &&
echo 'Enter 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}"; \

# Erase the credentials from local variables
clb_dev_pwd='';clb_dev_username=''

The response will be similar to:

{
   "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": ""
}

Copy the "access_token" value, it is the one that will be needed for the next step.