Trove Help Trove home

Authelia

Seamlessly integrate Authelia as your single sign-on (SSO) provider for Trove. Simplify user authentication, enhance security, and provide a streamlined login experience across your applications.

What You'll Achieve

With Authelia integration, you can:

How Authelia Integration Works

The Authentication Flow

Understanding the authentication flow helps troubleshoot issues and explains what happens behind the scenes:

  1. 🎫 User Initiates Login
    User attempts to access Trove and is redirected to Authelia's secure login portal. The original destination URL is preserved for automatic redirect after authentication.

  2. 🔑 Authelia Authenticates
    User enters credentials in Authelia's login page. Authelia validates the credentials against its user directory and verifies the user's identity.

  3. ✅ Token Exchange
    Authelia validates credentials and issues OAuth2 tokens (access token, ID token). These tokens contain user information and are cryptographically signed for security.

  4. 🚪 Access Granted
    Trove receives and validates the tokens, extracts user information, matches it with an existing Trove user account, and grants access to the authenticated user.

Setting Up Authelia

Step 1: Create OIDC Client in Authelia

The essential parts of the Authelia config are highlighted below, and should be adapted to your specific setup.

example.com will need changing to your actual domain name.

It's also best practice to change the client_id parameter to a randomly generated string, the following restrictions apply:

Valid Client ID’s have the following characteristics:

identity_providers:
  oidc:

    lifespans:
      access_token: 1h
      authorize_code: 1m
      id_token: 1h
      refresh_token: 90m
    enable_client_debug_messages: true
    enforce_pkce: public_clients_only
    cors:
      endpoints:
        - authorization
        - pushed-authorization-request
        - token
        - revocation
        - introspection
        - userinfo
      allowed_origins_from_client_redirect_uris: true

    claims_policies:
      legacy:
        id_token: ['email', 'email_verified', 'preferred_username', 'name']

    clients:
      - client_id: trove
        client_name: Trove
        public: true
        authorization_policy: two_factor
        claims_policy: legacy
        consent_mode: implicit
        require_pkce: true
        pkce_challenge_method: S256
        scopes:
          - offline_access
          - openid
          - profile
          - email
        redirect_uris:
          - https://trove.example.com/oauth2-callback
          - https://trove.example.com/*
        response_types:
          - code
        grant_types:
          - authorization_code
          - refresh_token

Configuring Trove

Step 2: Connect Trove to Authelia

Now configure Trove to use Authelia as the authentication provider. This is the final configuration step:

Trove OIDC Settings

  1. Open Trove Settings
    Go to Settings › OIDC in your Trove admin interface. You'll need administrator privileges to access this section.

  2. Configure OIDC Provider Enter the credentials you copied from Authelia:

    • Provider Name: Authelia (or your preferred display name)
      • This name appears on the login button, so make it recognizable to users
    • Client ID: Paste the Client ID from Authelia (trove)
      • Make sure there are no extra spaces before or after
    • Issuer URI: Paste the OpenID Configuration Issuer URL from Authelia without a trailing slash
      • Example: https://auth.example.com
    • Username Claim: preferred_username
    • Email Claim: email
    • Display Name Claim: name
    • Click Save to store the configuration

  3. Enable OIDC Authentication
    Under Login Methods, switch on OIDC Login to start using Authelia

    • When enabled, users will see a "Login with Authelia" button on the Trove login page
    • The standard username/password login will still be available unless specifically disabled

Testing the Integration

Step 4: Test Login with Authelia

Verify that the integration works correctly before rolling it out to users. Testing ensures a smooth experience:

Open an incognito/private browser window

Trove Opens

Managing Authentication

Disabling Authelia Authentication

If you need to temporarily disable or switch authentication methods (for maintenance or troubleshooting):

Disable OIDC

  1. Navigate to Authentication Settings
    Go to Trove → Settings › OIDC

  2. Disable OIDC
    Under Login Methods, switch off OIDC Login

    • This immediately disables Authelia authentication
    • Active sessions remain valid until they expire
    • New login attempts will use standard authentication

  3. Log Out
    Click Logout to end your current session and verify the change

  4. Standard Login Returns
    You'll be redirected to the standard Trove login page with username/password fields

Trove Login

Troubleshooting

Common Issues and Solutions

Authentication Fails:

Redirect Errors:

User Not Found:

"Invalid Client" Error:

Connection Refused:

SSL/Certificate Errors:

Viewing Logs

Authelia: Check application logs for OAuth-related events and errors
Trove: Review authentication logs in the application logs directory

Best Practices

Security Recommendations

Optimization Tips

User Experience

Additional Resources

Authelia is an open-source authentication and authorization server and portal fulfilling the identity and access management (IAM) role of information security in providing multi-factor authentication and single sign-on (SSO) for your applications via a web portal. Authelia is an OpenID Connect 1.0 Provider which is OpenID Certified™ allowing comprehensive integrations, and acts as a companion for common reverse proxies.