> For the complete documentation index, see [llms.txt](https://gift.icbest.ca/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gift.icbest.ca/settings/oidc-support.md).

# OIDC Support

OpenID connect allow you to connect to the app using a third-party auth provider like [Authelia](https://www.authelia.com/), [Authentik](https://goauthentik.io/), [keycloak ](https://www.keycloak.org/)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 admin dashboard or by manually editing the file which is in the mounted folder:

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