# User authentication

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

Note that in this installation guide we make you use Keycloak but you can use any OIDC compliant provider like Entra ID or Auth0. See the following gide for specific instructions for different provider and detailed authentication related configuration options.

{% content-ref url="../openid-connect-configuration" %}
[openid-connect-configuration](https://docs.onyxia.sh/admin-doc/openid-connect-configuration)
{% endcontent-ref %}

### Deploying Keycloak

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

Before anything open [`apps/keycloak/values.yaml`](https://github.com/InseeFrLab/onyxia-ops/blob/main/apps/keycloak/values.yaml) in your onyxia-ops repo and [change the passwords](#user-content-fn-1)[^1]. Also write down the [`keycloak.auth.adminPassword`](https://github.com/InseeFrLab/onyxia-ops/blob/bad75636d72c20c48f1b34ec08593df83ee6c9a6/apps/keycloak/values.yaml#L11), you'll need it to connect to the Keycloak console.

{% embed url="<https://app.tango.us/app/embed/dbb21e90-db2c-41f4-b2ab-5f8b9f4d33c0>" %}

{% hint style="info" %}
Try to remember, when you [update Onyxia in `apps/onyxia/Chart.yaml`](https://github.com/InseeFrLab/onyxia-ops/blob/bad75636d72c20c48f1b34ec08593df83ee6c9a6/apps/onyxia/Chart.yaml#L6) to also update [the Onyxia theme in `apps/keycloak/values.yaml`](https://github.com/InseeFrLab/onyxia-ops/blob/bad75636d72c20c48f1b34ec08593df83ee6c9a6/apps/keycloak/values.yaml#L69).
{% endhint %}

### 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](https://aws.amazon.com/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**.
      * Users **without** "Remember Me" will need to log in **every 2 weeks**:
        * Set **Session idle timeout**: `14 days`.
        * Set **Session max idle timeout**: `14 days`.
      * Users **who checked "Remember Me"** should stay logged in for **1 year**:
        * Set **Session idle timeout (Remember Me)**: `365 days`.
        * Set **Session max idle timeout (Remember Me)**: `365 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. 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** -> **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.

```diff
{
  "attributes": [
    {
      "name": "username",
      "displayName": "${username}",
      "validations": {
        "length": {
          "min": 3,
          "max": 255
        },
+       "pattern": {
+         "error-message": "${lowerCaseAlphanumericalCharsOnly}",
+         "pattern": "^[a-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.

```bash
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:

{% embed url="<https://github.com/InseeFrLab/onyxia-ops/commit/37faa6390c9bc8c1efddfd3488dc06b38427b424>" %}

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

<figure><img src="https://content.gitbook.com/content/x3LIftMZY501x5liXUPV/blobs/LqMfWG0hyEmGoTdJJrFu/image.png" alt=""><figcaption><p>The screen you shoud see when clicking on "login" in your Onyxia deployment</p></figcaption></figure>

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

{% content-ref url="data-s3" %}
[data-s3](https://docs.onyxia.sh/admin-doc/readme/data-s3)
{% endcontent-ref %}

[^1]: Search/replace CHANGEME


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onyxia.sh/admin-doc/readme/user-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.