This page describes a workflow that you can follow to use the Collaboratory.drive as a back-end for your service to store and read data inside a private user space.

Overview

Your OIDC 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 with existing users. This can be achieved by using the existing Seafile API (the tool behind the Collaboratory.drive).

Creating a service account in IAM

If you do not yet have an OIDC client for your service, see Registering an OIDC client.

Once you have an OIDC account, you need to modify your client to allow service accounts:

Creating the service account in the Drive

Once you have created the service account in IAM, the service account needs to be created in the Drive. This step requires IAM admin privileges so you cannot do it yourself. Send a request to support@ebrains.eu instead and make sure to include the following information:

1. The URL of this page: Create an IAM service account
2. Your client ID: e.g. "my-awesome-client"

Never share tokens or secrets.

Creating the user space

Once support confirms that the service account has been activated in the Drive, you can proceed by creating the user space in the Drive. The user space will be created in the Drive, in the default Library of the service account. Each user of your service will have its own user space.

The general process is the following:

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

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 Jupyter Notebooks, it will need to share it with the user:

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

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

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:

Fetch the access token from this response.

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

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

Fetching your service account's default library

Note: from this point, you can refer to the documentation of Seafile to make API calls to the Collaboratory.drive.

You will get a response in the form of:

The `repo_id` is the identifier of the default library of your service account.

Creating a folder for a given user

In order to isolate the data of individual users, you should create a folder for each user, based on a unique identifier of the user. The most secure identifier you can use is the `sub` as it is an internal unique identifier of IAM.

The `username` is also a valid unique identifier but, in some rare cases, they might be claimed by a different user in the future.

Creating a folder is done with the following call:

Please note that you cannot create a path of folders all at once. You will need to make one call at each level of your path.

Writing data to the user space

TODO

Fetching data from the user space

TODO

Sharing data with notebooks

The Collaboratory.drive is mounted in the Jupyter container of the user. This means that notebooks can access data stored in the Collaboratory.drive of the user.

Let's imagine your service generates data that should be ingested by a notebook. In order for the notebook to be usable by any user, the path to the data must be the same for each user.

When sharing a folder /path/to/the/shared_folder with a user, the folder becomes reachable at the path drive/share with me/shared_folder. As you can see, only the name of the folder is shared with the user.

Imagine you want to generate data per user and you want notebooks to refer to this data in a folder named my-awesome-client-data. You will need to create a folder in your service account's default library in the following form:

/path/to/user/spaces/in/your/library/${user-id}/my-awesome-client-data.

Make sure the folder starts with your OIDC client name or some other unique name. Once the folder is created, you will need to share it with the user.

Sharing a folder with a user