OIDC Support

OpenID connect allow you to connect to the app using a third-party auth provider like Authelia, Authentik, keycloak and more. With OIDC, users only need to authenticate with the provider once to access all configured applications without additional passwords.

Configuration

After any changes you need to restart the app to apply them. After entering the client ID the button for OIDC connection will appear on the login page. This uses the /login_oidc route then call /auth for the verification.

Connection Setup

To configure OIDC, add the following values to the .env file, either using the /setup route or by manually editing the file with a command like docker exec:

OIDC_CLIENT_ID=' '
OIDC_CLIENT_SECRET=' '
OIDC_SERVER_METADATA_URL=' '
OIDC_LOGOUT_URL=' '

You can find all those values quite easily in the provider's dashboard but here some hints: Server metadata URL usually end with this /.well-known/openid-configuration Logout URL usually end with this /logout

Scopes, Claims, and Database Field Mapping

The next parameters are used to compare the received values from the OIDC with the JSON users database.

PRIMARY_OIDC_FIELD='email'
SECONDARY_OIDC_FIELD='preferred_username'
PRIMARY_DB_FIELD='email'
SECONDARY_DB_FIELD='username'

These defaults are recommended but can be customized. Here are some common OIDC fields:

OIDC

You will need to confirm with the provider system but those are the most common used:

• given_name (the full name)

• email (used to register in the provider)

• preferred_username (username for login in the provider)

JSON

You can compare the previous values with the ones present in the JSON but under a different name.

• full_name

• email

• username

The app will check for matching values in these fields and log in the user if there is a match.

Recommendations

Using the default field mappings is recommended, as they are widely supported. This setup compares values from the OIDC provider and the app's database to ensure that at least one field matches, allowing user login.

Auto Registration

If a user attempts to log in via OIDC and no matching fields are found, they can create a profile in the app. This will redirect them to /setup_profile, where they can provide any additional information not supplied by the OIDC provider, such as their birthday, avatar, and full name. Auto-registration is disabled by default but can be enabled by setting ENABLE_AUTO_REGISTRATION=true in the .env file.

Disable Login Form

To enforce OIDC for users, set the environment variable ENABLE_DEFAULT_LOGIN to false, allowing only the OIDC button to be displayed.