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>/auth/oidc/callback

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

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

Authelia

In the Authelia admin interface, navigate to “Applications” and create a new application
Set the “Redirect URIs” to the callback URL according to above
Configure the scopes (required openid and email, optionally profile)
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):

authelia_oidc.yaml

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

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

Stump Configuration

OIDC is configured in the same manner as other Stump settings, through environment variables or the toml configuration file. See server configuration for more details.

Required Settings

Variable	Description	Example
`STUMP_OIDC_ENABLED`	Enable OIDC authentication	`true`
`STUMP_OIDC_ISSUER_URL`	The base URL of your OIDC provider	`https://auth.example.com/application/o/stump/`
`STUMP_OIDC_CLIENT_ID`	The client ID provided by your OIDC provider	`stump-client-id`
`STUMP_OIDC_CLIENT_SECRET`	The client secret provided by your OIDC provider	`super-secret-value`

Optional Settings

Variable	Default	Description
`STUMP_OIDC_SCOPES`	`openid,email,profile`	Additional scopes to request from the provider (comma-separated)
`STUMP_OIDC_ALLOW_REGISTRATION`	`true`	Allow automatic user registration via OIDC on first login
`STUMP_OIDC_DISABLE_LOCAL_AUTH`	`false`	Disable local username/password authentication when OIDC is enabled

Docker Compose Example

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'

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.

For information about user permissions and managing who can set passwords, see the User Permissions guide

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

⚠️

Some features, such as OPDS feeds, still require username/password authentication. Users will need to set a password (as described above) even when local authentication is disabled globally

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.

For instructions on migrating existing accounts to OIDC, see the CLI guide

Library Exclusions Permissions