OpenID Connect (OIDC)

Stump supports OpenID Connect (OIDC) authentication, allowing users to sign in using external identity providers like Authelia, Keycloak, PocketID, and others.

Provider Configuration

This section provides general guidance for configuring popular OIDC providers to work with Stump. I cannot feasibly cover every provider, however the below examples should give you a good starting point.

Callback URL

When configuring your OIDC provider, you will need to set the callback (redirect) URL to point to your Stump instance. The format is:

https://<your-stump-domain>/api/v2/auth/oidc/callback

If needed, you may also specify the logout URL as:

https://<your-stump-domain>/api/v2/auth/logout

Authelia

1. In the Authelia admin interface, navigate to "Applications" and create a new application
2. Set the "Redirect URIs" to the callback URL according to above
3. Configure the scopes (required openid and email, optionally profile)
4. Save the application and copy the client ID and secret for use in the Stump configuration

Authelia YAML

An example YAML configuration for Authelia is shown below (thanks to @wolsen9):

identity_providers:
  oidc:
    # --------------------------------------------------------------------------
    # Security Configuration
    # --------------------------------------------------------------------------
    # HMAC secret used for signing tokens (store as plain text, not hashed)
    # Recommended to not store directly in YAML, this is just for example purposes
    hmac_secret: 'supersecret1'
    # --------------------------------------------------------------------------
    # JSON Web Key Set (JWKS) Configuration
    # --------------------------------------------------------------------------
    jwks:
      - algorithm: 'RS256'
        use: 'sig'
        # Private key in PEM DER format (store as plain text, not hashed)
        # Replace with your actual RSA private key
        # Recommended to not store directly in YAML, this is just for example purposes
        key: '-----BEGIN RSA PRIVATE KEY-----'
    # --------------------------------------------------------------------------
    # Claims Policies
    # --------------------------------------------------------------------------
    # Describes how claims are mapped from the identity provider to Stump
    claims_policies:
      stump_policy:
        id_token:
          - 'email'
          - 'name'
    # --------------------------------------------------------------------------
    # Token Lifespans
    # --------------------------------------------------------------------------
    lifespans:
      access_token: '1 hour'
      authorize_code: '1 minute'
      id_token: '1 hour'
      refresh_token: '90 minutes'
    # --------------------------------------------------------------------------
    # OAuth/OIDC Clients
    # --------------------------------------------------------------------------
    clients:
      - client_id: 'Stump_OIDC' # Corresponds to STUMP_OIDC_CLIENT_ID
        client_name: 'Stump'
        # Client secret (stored hashed in the system)
        # Recommended to not store directly in YAML, this is just for example purposes
        client_secret: 'supersecret2' # Corresponds to STUMP_OIDC_CLIENT_SECRET
        redirect_uris:
          - 'https://stump.example.com/api/v2/auth/oidc/callback'
        claims_policy: 'stump_policy'
        consent_mode: 'implicit'

PocketID

1. In Pocket-ID create a new OIDC Client, name it, for example Stump
2. Set the launch URL if you would like to route to Stump from your PocketID dashboard
3. Set a logo for this OIDC Client if you would like to
4. Set the callback URLs according to above
5. Copy the Client ID and Client Secret for use in the Stump configuration

Zitadel

1. In the Zitadel Console, navigate to your project and create a new Web application with authentication method Code
2. Set the redirect URI to the callback URL according to above
3. Note the Project ID shown at the top of the project page (a numeric string like 360960386461073457)
4. Copy the Client ID from the application detail page (this is not the project ID or application ID) and the Client Secret generated when you create the application for use in the Stump configuration
5. Set STUMP_OIDC_EXTRA_AUDIENCES to the Project ID from step 3 — this is required because Zitadel adds the project ID to the JWT aud claim by default.

Zitadel Docker Compose Example

services:
  stump:
    image: aaronleopold/stump:latest
    environment:
      STUMP_OIDC_ENABLED: 'true'
      STUMP_OIDC_ISSUER_URL: 'https://your-zitadel-instance.com'
      STUMP_OIDC_CLIENT_ID: 'your-zitadel-client-id'
      STUMP_OIDC_CLIENT_SECRET: 'your-zitadel-client-secret'
      STUMP_OIDC_EXTRA_AUDIENCES: 'your-zitadel-project-id'
    ports:
      - '10801:10801'

Stump Configuration

OIDC can be configured using either environment variables or the TOML configuration file. See server configuration for more details.

Required Settings

Optional Settings

Configuration Examples

services:
  stump:
    image: aaronleopold/stump:latest
    environment:
      STUMP_OIDC_ENABLED: 'true'
      STUMP_OIDC_ISSUER_URL: 'https://auth.example.com/application/o/stump/'
      STUMP_OIDC_CLIENT_ID: 'stump-client-id'
      STUMP_OIDC_CLIENT_SECRET: 'super-secret-value'
      # Optional settings (and their defaults)
      # STUMP_OIDC_SCOPES: 'openid,email,profile'
      # STUMP_OIDC_ALLOW_REGISTRATION: 'true'
      # STUMP_OIDC_DISABLE_LOCAL_AUTH: 'false'
    ports:
      - '10801:10801'

# other configurations...
port = 10801

[oidc]
enabled = true
issuer_url = "https://auth.example.com/application/o/stump/"
client_id = "stump-client-id"
client_secret = "super-secret-value"
scopes = "openid,email,profile"
allow_registration = true
disable_local_auth = false

User Management

Setting Passwords for OIDC Users

OIDC users may optionally set a local password in Stump. This can be useful for accessing features that require password-based authentication (such as OPDS feeds). Users with the appropriate permissions can set their own passwords through the Stump interface.

Disabling Local Authentication

You can disable local username/password authentication globally by setting STUMP_OIDC_DISABLE_LOCAL_AUTH=true in your configuration. When enabled:

• The username/password login form will be hidden
• Only OIDC authentication will be available on the login page
• Existing local users will be unable to log in via username/password

Account Migration

Stump does not support automatic linking of existing local accounts to OIDC accounts. If you have existing users with read history, preferences, or other data that you want to migrate to OIDC accounts, you can use the Stump CLI migration tool.