# Configuration

This page provides some features that can be configured on Cytomine.

# Configure LS-AAI Identity Broker

Cytomine uses keycloak as IAM and also as a broker to negotiate with LS-AAI to authenticate users using authorization_code flow and go to https://127.0.0.1/iam/realms/cytomine/.well-known/openid-configuration (opens new window) for the metadata, for configuration follow steps below:

# A. Configure the broker

Access keycloak admin console https://127.0.0.1/iam/admin (opens new window) and authenticate using the default admin user and find the password for it in cytomine.yaml under KEYCLOAK_ADMIN_PASSWORD and notice this is not the cytomine admin.
Click Identity Providers in the menu.
Select Cytomine realm from the upper left corner
From the Add provider list, select OpenID Connect v1.0 or keycloak openID connect.
Redirect URI is prefilled
Enter display name as LS_AAI
Enter this link https://login.aai.lifescience-ri.eu/oidc/.well-known/openid-configuration in Discovery Endpoint for LS-AAI OIDC metadata
In client authentication select Client secret set as basic auth
Contact cytomine team at ULiège to get the client ID and client secret , click contact us button below
Click save
scroll down and click Advanced and toggle Backchannel Logout to ON
click save again

# B. Map claims to roles

The following config assigns the role admin to all external users and this is mandatory.

Go to Mappers tab click on add mapper
Enter AdminMapper for the mapper and keep sync mode override as inherit
Select Hardcoded Role Mapper
Click Select Role then filter by client and From client core select ADMIN role
Click save

once steps above are followed a new button appears in the login form to start the authentication process for users coming from other organizations.

# Datasets Importation

TIP

Importing does not create explicit copies or duplication of files, only database entries and symbolic links are created.

This section outlines the procedure for importing datasets, which are formatted according to the BP Dataset File Structure Standard (opens new window).

# Prerequisites

Cytomine Python client (opens new window) (v3.1.0+ recommended)
sdafs (opens new window) (optional)

TIP

sdafs is optional and only needed if you do not have the datasets on your filesystem.

The complete installation guide is available in the sdafs repository (opens new window).

Install go (https://go.dev/doc/install (opens new window))
Add the following line to your $HOME/.profile or /etc/profile (for a system-wide installation):

export PATH=$PATH:/usr/local/go/bin

Install sdafs

go install github.com/NBISweden/sdafs/cmd/sdafs@v0.0.23

Where v0.0.23 is the version you want to install

Follow sdafs usage (opens new window) documentation to download credentials.
Depending on the OS, edit user_allow_other variable in /etc/fuse.conf as explained in sdafs permissions (opens new window) section.
Create a folder to host the mount point

mkdir bp-datasets

Mount sdafs with the downloaded credentials to the created folder

sdafs --open --credentialsfile s3cmd-download.conf bp-datasets

The command is from the sdafs usage (opens new window) section.

The structure of the imported directory should follows:

root
|--- {DATASET_UUID}
|    |--- DATASET_{IDENTIFIER}
|         |--- METADATA
|         |    |--- dataset.xml
|         |    |--- policy.xml
|         |    |--- image.xml
|         |    |--- annotation.xml
|         |    |--- observation.xml
|         |    |--- observer.xml
|         |    |--- sample.xml
|         |    |--- staining.xml
|         |
|         |--- IMAGES
|         |    |--- IMAGE_{IDENTIFIER}
|         |    |    |--- *.dcm files of an Image
|         |    |--- IMAGE_{IDENTIFIER}
|         |    |    |--- *.dcm files of an Image
|         |
|         |--- ANNOTATIONS
|         |    |--- *.geojson

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

The METADATA and ANNOTATIONS directories are optional.

TIP

If you’re working with sdafs, the directories are already organised in the structure shown above.

# [Optional] Configuration

TIP

This configuration is optional if you planned to use the default location ./cytomine/data/dataset for importing your datasets.

Create .env in the cytomine folder and add the path to your dataset folder:

IMPORT_PATH=<path-to-dataset-folder>

Where <path-to-dataset-folder> is the path to your dataset folder.

If no .env file was provided, the default location is ./cytomine/data/dataset

WARNING

This step should be done before the docker compose up -d command in the Cytomine installation guide.

# Usage

Using the Python client in your locally cloned Cytomine directory, you can import the datasets with the following command:

python import_datasets.py --cytomine_core_host <cytomine-core-host> --cytomine_pims_host <cytomine-pims-host> --private_key <private-key> --public_key <public-key>

where <cytomine-core-host> and <cytomine-pims-host> is your Cytomine host (if local installation: http://127.0.0.1/ (opens new window)), <public-key> and <private-key> are your public and private keys (you can get them in the Cytomine Web-UI in Account).

WARNING

Several factors can slow down the importation:

You are using sdafs, it is currently slow the first time the data are loaded
You have a large amount of files on your filesystem

← Installation Guide Backup and restore →