# How to Configure OIDC_ONLY Mode for SSO-Only Authentication in TREK

> Secure your TREK instance by configuring OIDC_ONLY mode for SSO-only authentication. Disable password login and enforce OpenID Connect exclusively.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Set `OIDC_ONLY=true` in your environment variables to disable local password login and enforce OpenID Connect authentication exclusively, with the first SSO user automatically becoming the admin.**

TREK is an open-source platform that supports running in strict "SSO-only" mode, completely eliminating local username and password authentication in favor of OpenID Connect (OIDC). This configuration is controlled exclusively through the `OIDC_ONLY` environment variable and requires a properly configured identity provider.

## What OIDC_ONLY Mode Disables and Enables

When you configure `OIDC_ONLY=true`, TREK makes three critical architectural changes to the authentication flow:

- **Password authentication is completely disabled** – The local login and registration forms are removed from the UI, and the backend rejects password-based authentication attempts. The admin panel displays a notice indicating these settings are managed by `OIDC_ONLY` and cannot be changed at runtime.

- **OIDC provider becomes mandatory** – The system requires valid `OIDC_ISSUER` and `OIDC_CLIENT_ID` environment variables (and optionally `OIDC_CLIENT_SECRET`) to start. Without these, the SSO-only mode cannot function.

- **Automatic admin provisioning** – On a fresh installation with no existing users, the first successful authentication via your identity provider (IdP) is automatically granted administrator privileges, eliminating the need to create a local admin account first.

## Prerequisites for Enabling OIDC_ONLY

Before activating SSO-only mode, ensure you have:

1. A functional OpenID Connect provider (such as Auth0, Keycloak, or Azure AD)
2. The OIDC discovery endpoint URL (`OIDC_ISSUER`)
3. Client credentials registered with your provider (`OIDC_CLIENT_ID` and optionally `OIDC_CLIENT_SECRET`)
4. The public base URL of your TREK instance (`APP_URL`) for constructing redirect URIs

## Step-by-Step Configuration

### Configure Environment Variables

Add the following to your `.env` file or environment configuration:

```dotenv

# Required OIDC endpoints

OIDC_ISSUER=https://auth.example.com
OIDC_CLIENT_ID=trek
OIDC_CLIENT_SECRET=supersecret

# Enable SSO-only mode

OIDC_ONLY=true

# Public URL for callback handling

APP_URL=https://trek.example.com

```

Note that `OIDC_ONLY` is read at server startup from `process.env.OIDC_ONLY` and cannot be toggled from the Admin UI.

### Docker Compose Setup

In your [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml), pass the variables to the container:

```yaml
services:
  app:
    image: mauriceboe/trek:latest
    environment:
      - OIDC_ISSUER=https://auth.example.com
      - OIDC_CLIENT_ID=trek
      - OIDC_CLIENT_SECRET=supersecret
      - OIDC_ONLY=true
      - APP_URL=https://trek.example.com

```

### Kubernetes Helm Deployment

For Kubernetes installations using the TREK Helm chart, modify your [`values.yaml`](https://github.com/mauriceboe/TREK/blob/main/values.yaml):

```yaml
env:
  OIDC_ISSUER: https://auth.example.com
  OIDC_CLIENT_ID: trek
  OIDC_CLIENT_SECRET: supersecret
  OIDC_ONLY: "true"
  APP_URL: https://trek.example.com

```

## How the Authentication Logic Works

The enforcement of SSO-only mode occurs in [`server/src/services/authService.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/authService.ts), where the application checks the flag at runtime:

```typescript
// server/src/services/authService.ts
const oidcOnlyEnabled =
  process.env.OIDC_ONLY?.toLowerCase() === 'true' || get('oidc_only') === 'true';
...
env_override_oidc_only: process.env.OIDC_ONLY === 'true',

```

Because the flag is evaluated against `process.env.OIDC_ONLY` directly, the server must be restarted for changes to take effect. The configuration is also exposed to the frontend to conditionally render the SSO-only interface.

## Verifying Your SSO-Only Setup

After restarting the TREK server with the new configuration:

1. Navigate to the login page and confirm that only the **SSO** button is visible
2. Verify that username and password fields are completely absent
3. Attempt to log in via your IdP
4. Confirm that the first successful login grants administrator access to that user

## Summary

- **Environment-only setting**: `OIDC_ONLY` must be set as an environment variable; it cannot be changed through the Admin UI.
- **Complete lockout**: Local password login and registration are disabled when the flag is set to `true`.
- **Automatic admin**: The first user to authenticate via SSO becomes the admin on fresh installations.
- **Required variables**: `OIDC_ISSUER`, `OIDC_CLIENT_ID`, and `APP_URL` are mandatory when OIDC_ONLY is enabled.

## Frequently Asked Questions

### Can I switch OIDC_ONLY on and off from the Admin UI?

No. According to the source code in [`server/src/services/authService.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/authService.ts), `OIDC_ONLY` is strictly an environment-variable-only setting. The value is read at server startup and cannot be modified at runtime through the admin panel. You must restart the TREK server after changing this variable.

### What happens if I enable OIDC_ONLY without configuring an OIDC provider?

TREK requires valid `OIDC_ISSUER` and `OIDC_CLIENT_ID` values when `OIDC_ONLY` is enabled. Without these, the authentication system will not function properly, and users will be unable to access the application since both local and SSO authentication paths would be unavailable or misconfigured.

### How is the first admin account created when using OIDC_ONLY?

On a fresh installation with no existing users, TREK automatically promotes the first successful SSO authentication to administrator status. This eliminates the traditional bootstrap process of creating a local admin account; simply configure your IdP and log in to claim admin rights.

### Is OIDC_CLIENT_SECRET required for all OIDC providers?

No. The `OIDC_CLIENT_SECRET` is optional and depends on your specific provider's configuration. Some providers, particularly those using public clients or PKCE flows, may not require a client secret. However, `OIDC_ISSUER` and `OIDC_CLIENT_ID` are always mandatory when `OIDC_ONLY` is enabled.