Community App Developer Guide

Version 6.1 by allan on 2019/11/21 16:14

Developers can extend the Collaboratory capabilities by providing applications to its community of users.

This guide describes the steps to make this possible.

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

Becoming a contributor

The first step is for you to become a contributor. Contributors can register and manage applications within the Community Apps Catalogue.

Send an email to support@humanbrainproject.eu with a short summary of your intentions.

The support team will apply the permissions to your user: your account will be upgraded with developers privileges the next time you will login.

Only SGA2 accredited users will be automatically granted the contributor level.

Registering an application in the Catalogue

Collab authors find applications to add to their collabs in the Community Apps Catalogue.

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:

  1. get an access token from the `developer` client
  2. use the token to call the create endpoint
  3. 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:

# 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=''

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, 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:

# 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;

In case of success, the endpoint will return its representation of your client:

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

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:

# 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;

 Note that your need to provide your client id both in the endpoint URL and within the body of the request.

/!\   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.   /!\