# How to Configure OIDC SSO with Authentik or Keycloak for TREK

> Learn how to configure OIDC SSO for TREK using Authentik or Keycloak. Integrate your preferred OIDC provider easily by setting issuer URLs and client credentials.

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

---

**TREK supports OpenID Connect (OIDC) authentication through environment variables or the Admin panel, allowing you to integrate Authentik, Keycloak, or any OIDC-compatible provider by setting the issuer URL, client credentials, and discovery endpoints.**

TREK is an open-source application that supports external authentication via **OIDC Single Sign-On (SSO)**, enabling centralized user management through providers like Authentik or Keycloak. By configuring a set of environment variables or using the runtime admin interface, you can redirect users to your identity provider while maintaining secure credential storage. This guide covers the complete configuration process based on the TREK source code and official documentation.

## Core OIDC Configuration Variables

TREK exposes eight environment variables to control OIDC behavior. These parameters define the connection to your identity provider and control user experience settings.

### Required Environment Variables

At minimum, you must declare these three variables to enable OIDC:

- **`OIDC_ISSUER`** – The base URL of your identity provider (must use HTTPS in production). Example: `https://auth.example.com`
- **`OIDC_CLIENT_ID`** – The OAuth2 client identifier registered with your IdP. Example: `trek`
- **`OIDC_CLIENT_SECRET`** – The client secret generated by your IdP during application registration.

Additionally, **`APP_URL`** must be set to your TREK instance's public base URL (e.g., `https://trek.example.com`). TREK uses this value to construct the redirect URI (`/auth/oidc/callback`) that must exactly match the callback URL registered in your IdP.

### Optional Admin Mapping and Scopes

For advanced deployments, configure these optional variables:

- **`OIDC_DISPLAY_NAME`** – Text displayed on the login button (default: `SSO`).
- **`OIDC_ONLY`** – Set to `true` to disable local password authentication entirely.
- **`OIDC_ADMIN_CLAIM`** – The JWT claim containing group or role information (e.g., `groups`).
- **`OIDC_ADMIN_VALUE`** – The specific value within that claim that grants administrator privileges (e.g., `app-trek-admins`).
- **`OIDC_SCOPE`** – Space-separated OAuth scopes requested during authentication. Default: `openid email profile`.
- **`OIDC_DISCOVERY_URL`** – Full URL to the provider's discovery document when using non-standard paths (required for Authentik tenants).

All variable definitions are documented in [[`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md)](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md).

## Provider-Specific Setup Instructions

Different identity providers structure their discovery endpoints differently. TREK follows the OIDC Discovery spec but allows override via `OIDC_DISCOVERY_URL` when providers deviate from the standard `/.well-known/openid-configuration` path.

### Configuring Authentik for TREK

Authentik typically hosts the discovery document at a tenant-specific path rather than the root. If your Authentik instance uses a path like `/application/o/trek/.well-known/openid-configuration`, set the explicit discovery URL:

```ini
OIDC_ISSUER=https://auth.example.com
OIDC_DISCOVERY_URL=https://auth.example.com/application/o/trek/.well-known/openid-configuration

```

Without `OIDC_DISCOVERY_URL`, TREK attempts to fetch metadata from `{OIDC_ISSUER}/.well-known/openid-configuration`, which will fail for standard Authentik configurations.

### Configuring Keycloak for TREK

Keycloak follows the standard OIDC discovery URL pattern. You typically only need to specify the base issuer:

```ini
OIDC_ISSUER=https://auth.example.com/realms/trek

```

TREK automatically resolves the discovery document at `{OIDC_ISSUER}/protocol/openid-connect/.well-known/openid-configuration`. No `OIDC_DISCOVERY_URL` override is required unless you have customized the realm endpoints.

## Step-by-Step Implementation

Follow these steps to activate SSO for your TREK deployment.

### 1. Register the OIDC Client

Create a new OpenID Connect client in Authentik or Keycloak:

- **Client ID**: Choose a unique identifier (e.g., `trek`).
- **Client Secret**: Generate a secure random string.
- **Redirect URI**: Register exactly `https://your.trek.instance/auth/oidc/callback`.
- **Scopes**: Ensure `openid`, `email`, and `profile` are available.

### 2. Configure TREK Environment Variables

Create or modify your `.env` file or Docker Compose environment section:

```ini

# Public URL - must match the registered redirect URI base

APP_URL=https://trek.example.com

# Core OIDC settings

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

# Optional: Force SSO-only mode

OIDC_ONLY=true

# Optional: Admin group mapping (example for Authentik)

OIDC_ADMIN_CLAIM=groups
OIDC_ADMIN_VALUE=app-trek-admins

# Optional: Extended scopes

OIDC_SCOPE=openid email profile groups

# Authentik-specific: Non-standard discovery URL

OIDC_DISCOVERY_URL=https://auth.example.com/application/o/trek/.well-known/openid-configuration

```

For Docker Compose deployments, expose these variables in your [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml):

```yaml
services:
  trek:
    image: ghcr.io/mauriceboe/trek:latest
    ports:
      - "3000:3000"
    environment:
      - APP_URL=${APP_URL}
      - OIDC_ISSUER=${OIDC_ISSUER}
      - OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
      - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
      - OIDC_DISPLAY_NAME=${OIDC_DISPLAY_NAME:-SSO}
      - OIDC_ONLY=${OIDC_ONLY:-false}
      - OIDC_ADMIN_CLAIM=${OIDC_ADMIN_CLAIM}
      - OIDC_ADMIN_VALUE=${OIDC_ADMIN_VALUE}
      - OIDC_SCOPE=${OIDC_SCOPE:-openid email profile}
      - OIDC_DISCOVERY_URL=${OIDC_DISCOVERY_URL}
    volumes:
      - trek-data:/app/data
volumes:
  trek-data:

```

### 3. Verify the Integration

Restart the TREK container to load the new configuration. Navigate to your login page and confirm that a **"Sign‑in with SSO"** button appears. Test the complete flow by authenticating with a user account from your IdP.

Check the TREK logs if the button does not appear. Common issues include missing `APP_URL` values or `OIDC_ISSUER` URLs with trailing slashes that do not match the discovery document's `issuer` field exactly.

## Runtime Configuration via Admin Panel

TREK exposes a subset of OIDC settings in the **Admin → SSO** web interface. You can configure these fields at runtime without restarting:

- **Issuer URL** (`OIDC_ISSUER`)
- **Client ID** (`OIDC_CLIENT_ID`)
- **Client Secret** (`OIDC_CLIENT_SECRET`)
- **Display Name** (`OIDC_DISPLAY_NAME`)
- **Discovery URL** (`OIDC_DISCOVERY_URL`)

However, the following variables are **environment-only** and cannot be changed via the UI:

- `OIDC_ONLY`
- `OIDC_ADMIN_CLAIM`
- `OIDC_ADMIN_VALUE`
- `OIDC_SCOPE`

To disable password login entirely, you must set `OIDC_ONLY=true` in your environment variables before starting the container.

## Security and Persistence Considerations

TREK encrypts the `OIDC_CLIENT_SECRET` at rest using the **`ENCRYPTION_KEY`** environment variable. If you lose or change this key, the stored secret becomes unreadable and OIDC authentication will fail until you re-enter the credentials in the admin panel or update the environment variables.

For production deployments using the Helm chart, review the encryption key rotation guidelines in [[`charts/README.md`](https://github.com/mauriceboe/TREK/blob/main/charts/README.md)](https://github.com/mauriceboe/TREK/blob/main/charts/README.md).

If your identity provider runs on a private network or internal IP address, set `ALLOW_INTERNAL_NETWORK=true` to permit TREK to communicate with the IdP. By default, TREK blocks requests to private address ranges to prevent Server-Side Request Forgery (SSRF) attacks.

## Troubleshooting Common Issues

| Symptom | Likely Cause | Solution |
|---------|--------------|----------|
| "APP_URL is not configured" | `APP_URL` environment variable missing | Set `APP_URL` to your public base URL |
| "Issuer mismatch" | Trailing slash inconsistency in `OIDC_ISSUER` | Ensure `OIDC_ISSUER` exactly matches the `issuer` field in the discovery document |
| "Requests to private/internal network addresses are not allowed" | IdP on private IP/range | Set `ALLOW_INTERNAL_NETWORK=true` |
| Login fails after restart | `ENCRYPTION_KEY` changed | Re-enter `OIDC_CLIENT_SECRET` in Admin → SSO or restore the original encryption key |

Detailed OIDC configuration guidance is available in [[`wiki/OIDC-SSO.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/OIDC-SSO.md)](https://github.com/mauriceboe/TREK/blob/main/wiki/OIDC-SSO.md).

## Summary

- **TREK supports OIDC SSO** through environment variables and the Admin → SSO panel for runtime adjustments.
- **Authentik requires** `OIDC_DISCOVERY_URL` due to non-standard discovery paths, while **Keycloak uses** the standard issuer-based discovery.
- **`APP_URL` is mandatory** for OIDC to function, as it constructs the redirect URI callback.
- **`OIDC_CLIENT_SECRET` is encrypted** at rest with `ENCRYPTION_KEY`; losing this key requires reconfiguration.
- **Environment-only variables** (`OIDC_ONLY`, `OIDC_ADMIN_CLAIM`, `OIDC_ADMIN_VALUE`, `OIDC_SCOPE`) must be set before container startup.

## Frequently Asked Questions

### How do I disable local password login after configuring OIDC?

Set the environment variable `OIDC_ONLY=true` before starting TREK. This setting cannot be toggled via the Admin panel and completely removes the password login form, forcing all users to authenticate through your configured IdP. Alternatively, you can disable password login under **Admin → Settings** if you prefer a softer toggle.

### Why does TREK fail to connect to my Authentik discovery endpoint?

Authentik often places the discovery document at `/application/o/{client_id}/.well-known/openid-configuration` rather than the root `/.well-known/openid-configuration`. Set `OIDC_DISCOVERY_URL` to the full URL of your Authentik tenant's discovery document, or TREK will fail to fetch the provider metadata.

### What happens if I rotate the ENCRYPTION_KEY after setting up OIDC?

The `OIDC_CLIENT_SECRET` stored in TREK's database is encrypted with your `ENCRYPTION_KEY`. If you change this key without migrating the encryption, TREK cannot decrypt the secret and OIDC authentication will fail. You must either restore the original key or re-enter the client secret in **Admin → SSO** after the rotation.

### Can I map IdP groups to TREK admin privileges?

Yes. Configure `OIDC_ADMIN_CLAIM` to specify which JWT claim contains group information (commonly `groups` for Authentik or `realm_roles` for Keycloak), and set `OIDC_ADMIN_VALUE` to the exact group name that should receive admin rights. When users with this claim value log in, TREK automatically grants them administrator privileges.