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.

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: Auto-provisioning is disabled when DISABLE_SIGNUP=true, regardless of the OIDC_AUTO_PROVISION setting. This ensures consistent behavior: when signups are disabled, no new accounts can be created automatically.

To disable auto-provisioning while keeping signups enabled, 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. Check that email and email_verified claims are present
3. Verify email_verified is set to true (not false or missing)
4. Check Journiv logs for error messages

Related Topics

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