Single Sign-On (OIDC)

TREK supports login via any OpenID Connect (OIDC) provider — Google, Apple, Authentik, Keycloak, and more.

Setup

1. Register TREK as an OAuth/OIDC client at your provider
2. Set the Redirect URI to: https://your-trek-domain.com/api/auth/oidc/callback
3. In TREK: Admin Panel → Settings → Single Sign-On (OIDC)
4. Enter: Display Name, Issuer URL, Client ID, Client Secret
5. Save — the "Sign in with [Name]" button appears on the login page

Provider Examples

Google

1. Go to Google Cloud Console → Credentials
2. Create OAuth Client ID → Web application
3. Add redirect URI: https://your-domain.com/api/auth/oidc/callback
4. In TREK:
   • Display Name: Google
   • Issuer URL: https://accounts.google.com
   • Client ID + Secret from Google

Authentik

1. Create an OAuth2/OIDC Provider in Authentik
2. Set redirect URI to https://your-domain.com/api/auth/oidc/callback
3. In TREK:
   • Display Name: Authentik
   • Issuer URL: https://your-authentik.com/application/o/trek/
   • Client ID + Secret from Authentik

Keycloak

1. Create a Client in your Keycloak realm
2. Set redirect URI
3. In TREK:
   • Display Name: Keycloak
   • Issuer URL: https://your-keycloak.com/realms/your-realm
   • Client ID + Secret from Keycloak

How it Works

1. User clicks "Sign in with [Provider]" on the login page
2. Redirected to the provider for authentication
3. After login, redirected back to TREK with an authorization code
4. TREK exchanges the code for user info (email, name)
5. If a user with that email exists → linked and logged in
6. If no user exists and registration is allowed → new account created
7. First user via OIDC becomes admin

Account Linking

• If you register with email/password first, then login via OIDC with the same email → accounts are automatically linked
• Once linked, you can use both methods to log in
• A "SSO" badge appears in your Settings showing the linked provider

OIDC-Only Mode

To disable password-based authentication entirely and require all users to log in via OIDC:

environment:
  OIDC_ONLY: "true"

When enabled:

• The username/password login form is hidden
• Users can only authenticate via the configured OIDC provider
• Existing password-based accounts can still be accessed if they link their OIDC identity
• On a fresh install, there is no local admin account prompt — only OIDC login

This is useful for organizations that want to enforce SSO for all users.

Admin Role Mapping

Automatically assign or revoke admin roles based on OIDC claims:

environment:
  OIDC_ADMIN_CLAIM: groups       # The claim to check (default: "groups")
  OIDC_ADMIN_VALUE: trek-admins  # The value that grants admin

On every OIDC login, TREK checks the user's token. If the specified claim contains the specified value, the user is promoted to admin. If the value is absent, admin is revoked. This allows centralized role management through your identity provider (e.g. Authentik groups, Keycloak roles).

Invite Tokens + OIDC

Invite tokens are passed through the OIDC flow. If a user clicks an invite link and logs in via OIDC, the invite is consumed correctly and the user is registered even when public registration is disabled.

Two-Factor Authentication (2FA)

TREK supports TOTP-based two-factor authentication for an extra layer of security on password-based accounts.

Setup

1. Go to Settings → Security
2. Click Enable 2FA
3. Scan the QR code with a TOTP-compatible authenticator app (e.g. Google Authenticator, Authy, 1Password)
4. Enter the 6-digit code to confirm setup
5. Save the backup codes in a safe place

Once enabled, you will be prompted for a TOTP code after entering your password on each login. 2FA can be disabled in Settings with your current password and a valid code.

Security Notes

• Login is rate-limited to 10 attempts per 15 minutes
• OIDC uses the authorization code flow (not implicit)
• OIDC users can set a password in Settings to also use password login
• Registration rules still apply — if registration is disabled, only existing users or invite link holders can login via OIDC