Authentication model

LobeHub authenticates through its own Better Auth integration. Authelia is the OIDC identity provider; nginx is transport-only and does not run forward authentication for this application.

Browser flow

1. LobeHub offers the Authelia provider and no email or password form.
2. The browser is sent to issuer https://auth.loca.zone for an authorization-code flow.
3. Authelia authenticates under policy one_factor and uses implicit consent for client lobe.
4. Authelia returns to https://lobe.loca.zone/api/auth/callback/authelia with scopes openid, profile, and email.
5. LobeHub exchanges the code using client_secret_basic, provisions or resolves the account from the OIDC claims, and owns the resulting application session.

The existing operator identity exposes a non-empty email claim. This is required for useful account provisioning and was verified without exposing the identity’s password hash.

LobeHub controls

• provider configuration:
  • AUTH_SSO_PROVIDERS=authelia
  • AUTH_AUTHELIA_ID=lobe
  • AUTH_AUTHELIA_ISSUER=https://auth.loca.zone
  • AUTH_AUTHELIA_SECRET is loaded from the protected .env
• password boundary:
  • AUTH_DISABLE_EMAIL_PASSWORD=1
  • email and password registration and login are disabled
  • there is no local password or break-glass account
• client behavior:
  • desktop, API, and agent traffic reaches LobeHub directly through nginx
  • LobeHub, not nginx, decides whether a request needs an application session or bearer credential

Removed or unrelated auth variables are deliberately absent: NEXT_AUTH_*, CLERK_*, ACCESS_CODE, NEXT_PUBLIC_SERVICE_MODE, AUTH_URL, and NEXT_PUBLIC_AUTH_URL are not part of this deployment.

Authelia client

• client ID: lobe
• client name: LobeHub
• public client: false
• authorization policy: one_factor
• consent mode: implicit
• grant type: authorization_code
• response type: code
• scopes: openid, profile, email
• token endpoint authentication: client_secret_basic
• userinfo signed response algorithm: none
• redirect URI: https://lobe.loca.zone/api/auth/callback/authelia

No Authelia edge access-control rule names lobe.loca.zone. That absence is intentional rather than an omission.

Why there is no nginx auth gate

An nginx auth_request gate would act before Better Auth. Cookie-less desktop, API, and agent requests could receive an HTML redirect to Authelia instead of the protocol response expected from LobeHub. Native OIDC keeps browser sign-in within the application while preserving non-browser traffic.

The invariant is:

• browser identity: native Better Auth OIDC
• application session and API authorization: LobeHub
• TLS and reverse proxy: nginx
• no outer HTML-redirect gate on lobe.loca.zone

Secret custody

• plaintext client secret:
  • variable name: AUTH_AUTHELIA_SECRET
  • location: ~/dev/lobe/.env
  • file state: gitignored, mode 0600
• Authelia verifier digest:
  • location: ~/dev/services/authelia/config/secrets/oidc/lobe-client-secret.digest
  • file state: root-owned, mode 0600
• public template:
  • .env.example contains names and placeholders only
• handling rule:
  • never print, quote, commit, or render either secret
  • use sudo -n docker compose config --quiet, never the interpolated rendering form

See environment for the full variable register and troubleshooting for OIDC fault isolation.