Oneliner

TLDR. Here is how you can get an Onyxia instance running in a matter of seconds.

With this, you will obtain an instance operating in a degraded mode, which lacks features such as authentication, S3 explorer, secret management, etc. However, you will still have the capability to launch services from the catalog.

Step by step installation guide

In this section, we will set up Onyxia from the ground up, along with all the associated technologies. This includes for S3, for OIDC, and for managing secrets.

Provision a Kubernetes cluster

First you'll need a Kubernetes cluster. If you have one already you can skip this section.

Installing Onyxia using helm

In this section we assume that:

• You have a Kubernetes cluster and kubectl configured

• onyxia.my-domain.net and *.lab.my-domain.net are pointing to your cluster's external address. my-domain.net being a domain that you own. You can customise "onyxia" and "lab" to your liking, for example you could chose datalab.my-domain.net and *.kub.my-domain.net.

• You have an ingress controller configured with a default TLS certificate for *.lab.my-domain.net and onyxia.my-domain.net.

You can now access https://onyxia.my-domain.net and start services. Congratulations! 🥳

Enabling user authentication

At the moment there is no authentication process, everyone can access our platform and and start services.

Let's setup Keycloak to enable users to create account and login to our Onyxia.

You can now login to the administration console of https://auth.lab.my-domain.net and login using the credentials you have defined with KEYCLOAK_USER and KEYCLOAK_PASSWORD.

1. Create a realm called "datalab" (or something else), go to Realm settings

   1. On the tab General

      1. User Profile Enabled: On

   2. On the tab login

      1. User registration: On

      2. Forgot password: On

      3. Remember me: On

   3. 1. From: noreply@lab.my-domain.net

      2. Host: email-smtp.us-east-2.amazonaws.com

      3. Port: 465

      4. Authentication: enabled

      5. Username: **************

      6. Password: ***************************************

      7. When clicking "save" you'll be asked for a test email, you have to provide one that correspond to a pre-existing user or you will get a silent error and the credentials won't be saved.

   4. On the tab Themes

      1. Login theme: onyxia-web (you can also select the login theme on a per client basis)

      2. Email theme: onyxia-web

   5. On the tab Localization

      1. Internationalization: Enabled

      2. Supported locales: <Select the languages you wish to support>

   6. On the tab Token

      1. SSO Session Idle: 14 days - This setting and the following two are so that when the user click "remember me" when he logs in, he dosen't have to loggin again for the next two weeks.

      2. SSO Session Idle Remember Me: 14 days

      3. SSO Session Max Remember Me: 14 days

2. Create a client called "onyxia"

   1. Root URL: https://onyxia.my-domain.net/

   2. Valid redirect URIs: https://onyxia.my-domain.net/*

   3. Web origins: *

   4. Login theme: onyxia-web

3. In Authentication (on the left panel) -> Tab Required Actions enable and set as default action Therms and Conditions.

Now you want to ensure that the username chosen by your users complies with Onyxia requirement (only alphanumerical characters) and define a list of email domain allowed to register to your service.

Go to Realm Settings (on the left panel) -> Tab User Profile (this tab shows up only if User Profile is enabled in the General tab and you can enable user profile only if you have started Keycloak with -Dkeycloak.profile=preview) -> JSON Editor.

Now you can edit the file as suggested in the following DIFF snippet. Be mindful that in this example we only allow emails @gmail.com and @hotmail.com to register you want to edit that.

Now our Keycloak server is fully configured we just need to update our Onyxia deployment to let it know about it.

Update the onyxia-values.yaml file that you created previously, don't forget to replace all the occurence of my-domain.net by your actual domain.

Now that you have updated onyxia-values.yaml restart onyxia-web with the new configuration.

Now your users should be able to create account, log-in, and start services on their own Kubernetes namespace.

S3 Storage

Create a Keycloak client for Accessing Keycloak

Before configuring MinIO, let's create a new client for Keycloak (from the previous existing "datalab" realm).

Create a client called "minio".

1. Client ID: minio

2. Client Protocol: openid-connect

3. Root URL: https://minio.lab.my-domain.net/

Complete the content of client "minio" with the following values.

1. Access Type: confidential

2. Valid Redirect URIs (two values are required): https://minio.lab.my-domain.net/* and https://minio-console.lab.my-domain.net/*

3. Web origins: *

Save the content, a new tab called Credentials must be appear. Navigate to Credentials tab and copy the secret value for the next section (KEYCLOAK_MINIO_CLIENT_SECRET).

Navigate to Mappers tab and create a protocol Mapper.

1. Name: policy

2. Mapper Type: Hardcoded claim

Complete the content of Mapper "policy" with the following values.

1. Token Claim Name: policy

2. Claim value: stsonly

3. Add to ID token: on

4. Add to access token: on

5. Add to userinfo: on

Install MinIO

MinIO is now deployed and is accessible on the console url.

By default, there are 16 MinIO containers running. If this number is too large for your Kubernetes cluster, you can limit it by configuring the 'replicas' key.

Create a Keycloak Client for Onyxia/MinIO

Before configuring the onyxia region to create tokens we should go back to Keycloak and create a new client to enable onyxia-web to request token for MinIO. This client is a little bit more complexe than other if you want to manage durations (here 7 days) and this client should have a claim name policy and with a value of stsonly according to our last deployment of MinIO.

From "datalab" realm, create a client called "onyxia-minio"

1. Client ID: onyxia-minio

2. Client Protocol: openid-connect

3. Root URL: https://onyxia.my-domain.net/

Complete the content of client "onyxia-minio" with the following values.

1. Access Type: public

2. Valid Redirect URIs: https://onyxia.my-domain.net/*

3. Web origins: *

4. Advanced Settings 1. Access Token Lifespan : 7 days 2. Client Session Idle : 7 days 3. Client Session Max: 7 days

Save the content and navigate to Mappers tab and create two protocol Mappers.

Create the first Mapper called "policy".

1. Token Name: policy

2. Mapper Type: Hardcoded claim

3. Token Claim Name: policy

4. Claim value: stsonly

5. Add to ID token: on

6. Add to access token: on

7. Add to userinfo: on

Create the second Mapper called "audience-minio".

1. Token Name: audience-minio

2. Mapper Type: Audience

3. _Included Custom Audience _: minio

4. Add to ID token: on

5. Add to access token: on

Update Onyxia

Vault

Onyxia-web use vault as a storage for two kinds of secrets : 1. secrets or information generate by Onyxia to store differents values (ui preferences for example) 2. user secrets Vault must be configured with JWT or OIDC authentification methods.

As vault need to be initialized with a master key, It can't be directly configured with all parameters such as oidc or access policies and roles. So first step we create a vault with dev mode (do not use this in production and do your initialization with any of the recommanded configuration : shamir, gcp, another vault)

Create a client called "vault"

1. Root URL: https://vault.lab.my-domain.net/

2. Valid redirect URIs: https://vault.lab.my-domain.net/*

3. Web origins: *