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

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:

# 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, pass the variables to the container:

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:

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, where the application checks the flag at runtime:

// 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}