OIDC/SSO Authentication

Journiv supports OpenID Connect (OIDC) for single sign-on (SSO) authentication. This allows users to authenticate using their existing identity provider (IdP) instead of creating separate Journiv accounts.

Overview

OIDC integration enables:

• Single Sign-On (SSO) - Users authenticate with their existing IdP
• Centralized user management - Manage users in your IdP, not in Journiv
• Automatic account provisioning - New users are created automatically on first login
• Enhanced security - Leverage your IdP's security features (MFA, password policies, etc.)

Requirements

Journiv uses a strict, standards-compliant OpenID Connect (OIDC) implementation for security and account safety.

Your Identity Provider must provide the following claims during authentication:

{
  "email": "user@example.com",
  "email_verified": true
}

Required Claims:

• email - User's primary email address
• email_verified - Must be present and set to true

Journiv will not authenticate users with unverified emails. This prevents spoofed identities, accidental account takeovers, and unsafe automatic user creation.

Environment Variables

Configure OIDC using these environment variables:

Note: REDIS_URL is required when OIDC is enabled. Redis is used to store OIDC state during the authentication flow.

Basic Configuration

Step 1: Configure Your Identity Provider

In your IdP (Keycloak, Authentik, Authelia, etc.), create a new OIDC client with:

• Client ID: Choose a unique identifier (e.g., journiv-client)
• Client Secret: Generate a secure secret
• Redirect URI: https://your-domain.com/api/v1/auth/oidc/callback (must match exactly)
• Grant Types: Authorization Code
• Response Types: Code

Step 2: Configure Journiv

Set the following environment variables:

OIDC_ENABLED=true
OIDC_ISSUER=https://keycloak.example.com/realms/journiv
OIDC_CLIENT_ID=journiv-client
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URI=https://journiv.example.com/api/v1/auth/oidc/callback
REDIS_URL=redis://redis:6379/0

Step 3: Configure Claims

Ensure your IdP is configured to include the required claims (email and email_verified) in the OIDC token. See provider-specific instructions below.

Step 4: Restart Journiv

After configuring environment variables, restart your Journiv instance:

docker compose restart <journiv-app-container>

Replace <journiv-app-container> with your actual service/container name (e.g., journiv, journiv-backend, etc.).

Redirect URI Matching

OIDC redirect URIs must match exactly (trailing slashes matter).

If Journiv is configured with:

https://journiv.example.com/api/v1/auth/oidc/callback

Then your Identity Provider must use the exact same URL.

Incorrect (will fail):

https://journiv.example.com/api/v1/auth/oidc/callback/

Correct:

https://journiv.example.com/api/v1/auth/oidc/callback

OIDC redirect URI matching is string-exact by specification. Journiv does not auto-correct or ignore mismatches for security reasons.

Provider-Specific Configuration

Authentik

When using Authentik as your OIDC provider, additional configuration is required.

email_verified Claim

Authentik does not always include email_verified by default. You must:

1. Create a custom Attribute / Expression Policy
2. Map or force the claim:

email_verified: true

or bind it to Authentik's internal email verification state.

Without this, Journiv login will fail.

Authelia

When using Authelia as your OIDC provider, you must configure claims policies to ensure required claims are included in OIDC tokens.

Claims Policies

Authelia uses claims policies to control which identity claims are included in OIDC tokens. The Journiv client must receive at least the required claims (email and email_verified).

Example Authelia Configuration

Create a claims policy in your Authelia configuration:

claims_policies:
  default:
    id_token:
      - email
      - email_verified
      - preferred_username
      - name

Then, assign this claims policy to your Journiv OIDC client:

clients:
  - id: journiv-client
    secret: your-client-secret
    claims_policy: 'default'

Important: Without an assigned claims policy, Authelia may authenticate successfully but omit required claims, causing Journiv auto-provisioning to fail. Always ensure your Journiv client has a claims policy that includes at least email and email_verified.

Authentication Modes

Journiv supports flexible OIDC configuration to match your security requirements:

Hybrid Mode (Default)

Both password and OIDC authentication are available:

OIDC_ENABLED=true
OIDC_ONLY=false
DISABLE_SIGNUP=false

Users can:

• Sign up with email/password
• Sign in with email/password
• Sign in with OIDC

OIDC-Only Mode

Only OIDC authentication is allowed. Password fields are completely hidden from the UI:

OIDC_ENABLED=true
OIDC_ONLY=true
OIDC_AUTO_PROVISION=true

Users can:

• Sign in with OIDC only
• Auto-register on first OIDC login (if OIDC_AUTO_PROVISION=true)

When to use: Ideal for enforcing Single Sign-On (SSO) authentication exclusively.

Important: When OIDC_ONLY=true:

• Password login and signup forms are hidden from the UI
• Existing password users can no longer log in with passwords (they must use OIDC)
• The first user (bootstrap) can still be created via password to set up the instance

Controlled Registration with OIDC

Block password signups while allowing OIDC auto-provisioning:

OIDC_ENABLED=true
OIDC_AUTO_PROVISION=true
DISABLE_SIGNUP=true

Users can:

• Sign in with email/password (existing users)
• Sign in with OIDC
• Auto-register via OIDC (new users)

Cannot:

• Sign up with email/password

When to use: Perfect for gradually migrating to SSO while keeping existing password users functional.

Fully Closed Instance

Require admin-created accounts only:

OIDC_ENABLED=true
OIDC_AUTO_PROVISION=false
DISABLE_SIGNUP=true

Users can:

• Sign in with email/password (admin-created accounts)
• Sign in with OIDC (admin-created accounts can link)

Cannot:

• Self-register via any method

When to use: Maximum control over who can access your Journiv instance.

Auto-Provisioning

When OIDC_AUTO_PROVISION=true (default), Journiv automatically creates user accounts on first OIDC login. The new user will have:

• Email address from the OIDC email claim
• Username derived from email (before @)
• No password (authentication only via OIDC)

Important: OIDC_AUTO_PROVISION works independently of DISABLE_SIGNUP. This allows you to block password-based signups while still allowing new OIDC users to auto-register.

To disable auto-provisioning, set:

OIDC_AUTO_PROVISION=false

When disabled, users must be manually created in Journiv before they can log in via OIDC.

Troubleshooting

OIDC Not Working

Basic checks:

• Ensure REDIS_URL is set (required for OIDC)
• Verify OIDC_REDIRECT_URI matches provider configuration exactly
• Check OIDC_ISSUER is accessible
• Verify client credentials are correct

Missing email_verified Claim

If authentication fails with claims-related errors, your Identity Provider may not be providing the email_verified claim. Ensure your IdP includes this claim and sets it to true. See the provider-specific configuration sections above for setup instructions.

Redirect URI Mismatch

If you see login loops or callback errors, check:

• Trailing slashes (must match exactly)
• HTTP vs HTTPS scheme
• Domain and port
• Path casing

The redirect URI in your IdP configuration must match OIDC_REDIRECT_URI exactly.

Auto-Provisioning Not Working

If users aren't being created automatically:

1. Verify OIDC_AUTO_PROVISION=true
2. Verify OIDC_ENABLED=true
3. Check that email and email_verified claims are present
4. Verify email_verified is set to true (not false or missing)
5. Check Journiv logs for error messages

Note: Unlike previous versions, OIDC_AUTO_PROVISION now works independently of DISABLE_SIGNUP. You can block password signups while still allowing OIDC auto-provisioning.

OIDC-Only Mode Not Working

If password fields are still visible when OIDC_ONLY=true:

1. Verify OIDC_ENABLED=true (required for OIDC_ONLY)
2. Restart your Journiv instance after changing environment variables
3. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
4. For mobile apps, perform a full app restart (not hot reload)
5. Verify the instance config endpoint returns oidc_only: true by checking /api/v1/instance/config

Related Topics

• Environment Variables - Complete environment variable reference
• Getting Started - Learn the basics of using Journiv
• Troubleshooting - Common issues and solutions