Storing data in user space

Version 6.1 by allan on 2019/11/25 14:29

This article describes a workflow that you can follow to use the Collaboratory.drive as a backend for your service to be able to store and read data inside a privatre user space.

Solution description

Your Keycloak client can be setup to have a service account linked to it. This service account being seen as a user by Keycloak, it can log in the Collaboratory.drive to have its user account synchronised there.

From this point, everything is set up to let your service account create and share files and folders to existing users. This can be achieved by using the existing Seafile API (the tool behind the Collaboratory.drive).

Creating a service account

If needed, follow the guide to create an OpenID Connect client.

You will need to modify your client to allow service accounts:

# Set your registration token
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",
        "serviceAccountsEnabled": true
    }' |

# Prettify the JSON response
json_pp;

Creating a user account for the service account in the Collaboratory.drive

This step requires admin privileges. Please send a request to support@humanbrainproject.eu in order to get help.

The steps for the admins are described are the following:

get the service account sub
enable the service account user
impersonate the service account
log in Collaboratory.drive

Getting the service account sub

One way to get the service account is to request a token with its credentials.

# Set the client id and secret
clb_client_id=...
clb_client_secret=...

# Call the token endpoint
curl -X POST https://iam-dev.humanbrainproject.eu/auth/realms/hbp/protocol/openid-connect/token \
-d 'grant_type=client_credentials' \
-d "client_id=${clb_client_id}" \
-d "client_secret=${clb_client_secret}" |

# Prettify the JSON response
json_pp;

Fetch the access token from the response and use a tool to decode its payload. https://jwt.io/ is one option. Copy the sub from the payload.

Enabling the service account user

Navigate to https://iam.humanbrainproject.eu/auth/admin/master/console/#/realms/hbp/users/$sub (replacing $sub with the value you got at the previous step).

Set the "Email Verified" value to "On" and remove any "Required User Actions".

You can now impersonate the user and log in the Collaboratory.drive, which will create the user account for the service account.

Creating the user space

The general process is the following:

Fetch a token for your service account to be able to discuss with the drive API.
Your service needs to get its default library id. It is where it will create the users' spaces.
For a given user, your service should create a folder, using a unique identifier (either the sub, username or email).

From this point, your service can now store and read data linked to users accounts.

If your service needs the data to be available in notebooks, it will need to share it with the user:

Inside the user folder, your service should create a folder with a name that would be common across users.
Your service should now share the inside folder with the user.

This way, notebooks will be able to refer to your service data with a common path for every user.

Getting an API token

The first step is to fetch an access token for your service account. This can be done with the following request:

The response will be similar to:

{
  "expires_in" : 108000,
  "not-before-policy" : 1563261088,
  "access_token" : "eyJhbGciOiJSU...",
  "session_state" : "4882dbae-56dc-4a91-b8ae-8ad07117d4af",
  "refresh_expires_in" : 14400,
  "refresh_token" : "eyJhbGciOiJIUz...",
  "token_type" : "bearer",
  "scope" : "openid roles email"
}

Fetch the access token from this response.

The next step is to get an API token with the access token:

# Set the access token value
clb_access_token=...

# Call the token endpoint
curl -X GET https://drive.humanbrainproject.eu/api2/account/token/ \
-H "Authorization: Bearer ${clb_access_token}"

The response will look like 1c1345da8a99b36168afef92df7f83af8b4ca6f0. This is the API token that you will need to use in your Authorization header to discuss with the Collaboratory.drive API.

Note that, unlike access tokens , the API token needs an authorisation header in the form of "Authorization: Token your-api-token" (and not Bearer!).