How to Configure OIDC SSO with Authentik or Keycloak for TREK

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

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:

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:

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:

# 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:

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

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

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.

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