v8
Home GitHub

🔑User authentication

Using Keycloak to enable user authentication

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

Note that in this instalation guide we make you use Keycloak but you can use any identity server that is Open ID Connect compliant.

Deploying Keycloak

We're going to install Keycloak just like we installed Onyxia.

Before anything open apps/keycloak/values.yaml in your onyxia-ops repo and . Also write down the keycloak.auth.adminPassword, you'll need it to connect to the Keycloak console.

Try to remember, when you update Onyxia in apps/onyxia/Chart.yaml to also update the Onyxia theme in apps/keycloak/values.yaml.

Configuring Keycloak

You can now login to the administration console of https://auth.lab.my-domain.net/auth/ and login using username: keycloak and password: <the one you've wrote down earlier>.

  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. On the tab email, we give an example with AWS SES, if you don't have a SMTP server at hand you can skip this by going to Authentication (on the left panel) -> Tab Required Actions -> Uncheck "set as default action" Verify Email. Be aware that with email verification disable, anyone will be able to sign up to your service.

      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 Session.

      1. SSO Session Idle:

      2. SSO Session Max:

      3. SSO Session Idle Remember Me:

      4. SSO Session Max Remember Me: 14 days

  2. Create a client with client ID "onyxia"

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

    2. Valid redirect URIs: https://datalab.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.

{
  "attributes": [
    {
      "name": "username",
      "displayName": "${username}",
      "validations": {
        "length": {
          "min": 3,
          "max": 255
        },
+       "pattern": {
+         "error-message": "${alphanumericalCharsOnly}",
+         "pattern": "^[a-zA-Z0-9]*$"
+       },
        "username-prohibited-characters": {}
      }
    },
    {
      "name": "email",
      "displayName": "${email}",
      "validations": {
        "email": {},
+       "pattern": {
+         "pattern": "^[^@]+@([^.]+\\.)*((gmail\\.com)|(hotmail\\.com))$"
+       },
        "length": {
          "max": 255
        }
      }
    },
...

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

Updating the Onyxia configuration

In your GitOps repo you now want to update your onyxia configuration. 

git clone https://github.com/<your-github-org>/onyxia-ops
cd onyxia-ops
cd apps/onyxia
mv values-keycloak-enabled.yaml values.yaml
git commit -am "Enable keycloak"
git push

Here is the DIFF of the onyxia configuration:

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

Next step in the installation proccess it to enable all the S3 related features of Onyxia:

🗃️pageData (S3)

Last updated