brain/web/docs/AUTHELIA.md

Connecting computer to Authelia (OIDC)

computer includes an Authelia OpenID Connect provider scaffold, but end-to-end sign-in is intentionally stubbed. Real credentials register the NextAuth provider; the login button and sign-in callback still block it until a developer implements mapping to local Go users.

This guide covers configuration you can prepare now and the developer work needed to finish the connection. Email/password login remains available. The client-managed OIDC flow runs on the trusted Next.js server; Go owns local users, accounts, and data authorization.

---

1. Current implementation

Paths in this table are relative to the repository root.

Piece	File	Current behavior
Config detection	web/lib/oidc-config.ts	enabled means all three OIDC variables contain non-placeholder values; it does not verify connectivity or a working login
Auth provider	web/auth.ts	Registers provider authelia when configured, but callbacks.signIn rejects every Authelia sign-in
Login page	web/app/login/client.tsx	oidcReady = false keeps the button disabled even with real credentials
Settings → OIDC	web/app/(app)/settings/client.tsx	Shows configuration status, issuer, and callback URL; explicitly says integration is pending
Go OIDC handlers	internal/oidc/provider.go	Status reports configuration; login and callback return 501

A value counts as "not set" if it is empty or looks like a placeholder. These are matched case-insensitively: REPLACE_ME, changeme, placeholder, anything containing example.com/.org/.net, <...>, values starting with your_/your-, or todo.

All three variables must hold real values before the NextAuth provider is registered. The readiness gate and identity mapping are separate requirements.

The root .env.example supplies:

OIDC_ISSUER=REPLACE_ME
OIDC_CLIENT_ID=REPLACE_ME
OIDC_CLIENT_SECRET=REPLACE_ME

Setting these values prepares the configuration. Complete section 4 before expecting users to sign in through Authelia.

---

2. What to configure in Authelia

The example uses Authelia 4.39 syntax. Authelia must have its OIDC provider configured, be served over valid HTTPS, and be reachable from both the user's browser and the Next.js container. See the upstream OIDC provider and client configuration documentation for your installed version.

2.1 Generate a client secret

docker run --rm authelia/authelia:4.39 authelia crypto hash generate pbkdf2 \
  --variant sha512 --random --random.length 72 --random.charset rfc3986

This prints:

• Random Password: the plain secret. It goes into computer as OIDC_CLIENT_SECRET.
• Digest: the hashed secret. It goes into Authelia's client_secret.

2.2 Register the computer client (configuration.yml)

Merge this example into the existing OIDC provider configuration. Replace the client secret digest and public app hostname; keep your existing provider signing keys, HMAC secret, and other clients.

identity_providers:
  oidc:
    # jwks / hmac_secret must already be configured for OIDC to work
    claims_policies:
      computer:
        # Include these identity claims in the ID token.
        id_token: ['email', 'email_verified', 'name', 'preferred_username']
    clients:
      - client_id: 'computer'
        client_name: 'computer'
        client_secret: '$pbkdf2-sha512$310000$...'   # Digest from 2.1
        public: false
        authorization_policy: 'two_factor'          # or 'one_factor'
        consent_mode: 'explicit'
        claims_policy: 'computer'
        redirect_uris:
          - 'https://<COMPUTER_HOST>/api/auth/callback/authelia'
        scopes: ['openid', 'profile', 'email']
        grant_types: ['authorization_code']
        response_types: ['code']
        token_endpoint_auth_method: 'client_secret_basic'

Validate the configuration and restart your Authelia deployment after editing.

Redirect URI rule: it must exactly match <NEXTAUTH_URL>/api/auth/callback/authelia, including scheme, hostname, port if present, and path. For an HTTPS deployment, use https://<COMPUTER_HOST>/api/auth/callback/authelia.

The callback is handled by NextAuth on the web app, not the Go API. Forward /api/auth/* to Next.js in your reverse proxy. The identically named direct-Go callback on port 8080 is a deliberate 501 stub.

2.3 Users

Provide email and profile claims for Authelia users. Automatic local account creation and linking are not implemented yet. The developer integration must define account provisioning and verify ownership before linking an existing email/password account; matching an email string alone is not enough.

---

3. What to configure in computer

Set these environment variables in the root .env or hosting environment. Compose passes the OIDC variables to the API and web containers. Replace the sample hostnames with your actual hosts.

Variable	Example	Notes
NEXTAUTH_URL	https://computer.company.tld	Public web app URL; determines the callback
COOKIE_SECURE	1	For an HTTPS deployment
OIDC_ISSUER	https://auth.company.tld	Exact issuer advertised in Authelia's discovery document
OIDC_CLIENT_ID	computer	Must match client_id in Authelia
OIDC_CLIENT_SECRET	(plain secret from 2.1)	The plain value, not the digest

Keep the existing AUTH_SECRET: changing it makes stored IMAP passwords unreadable. The client secret is a separate value and stays server-side.

The default Compose ports bind to localhost. Configure an HTTPS reverse proxy for the public web URL before using these HTTPS settings; see RUNNING.md.

Apply environment changes from the repository root:

docker compose up -d

Open Settings → OIDC to confirm the three variables are set. With real values it shows Configured … Client integration is still pending. This is configuration confirmation, not a successful connection test.

---

4. Developer handoff: complete local identity mapping

NextAuth handles OIDC discovery, authorization, token exchange, and token validation. The remaining integration must connect that verified identity to the PostgreSQL users that Go authorizes.

1. Add trusted Go-backed identity lookup/provisioning. No provisioning endpoint is supplied yet. Any new endpoint must authenticate calls from the trusted Next server, and accept only identities obtained after OIDC verification. Define first-login account creation and an explicit policy for linking existing accounts.
2. Persist the external identity link. Use the User and Account tables in db/schema.sql to associate provider authelia and its verified subject with a local User.id. Validate the configured issuer as part of the flow. Returning users must resolve to the same local user.
3. Update web/auth.ts. Replace the unconditional Authelia rejection in callbacks.signIn with the completed lookup/provisioning flow. Ensure the JWT/session callbacks store the resolved local User.id, rather than the OIDC profile's sub. web/lib/api.ts signs API assertions for the session ID, and Go expects that ID to identify a real local user.
4. Enable the login readiness gate. Update oidcReady in web/app/login/client.tsx only after identity mapping works. Retain the configuration check for the three OIDC variables.
5. Rebuild and verify. Run docker compose up -d --build, then perform the checks in section 5.

Keep the authorization-code callback on Next.js. Completing this integration does not require turning Go's placeholder login/callback routes into another OIDC client. Simply enabling the button or accepting sub as the local user ID will not make authenticated Go data access work.

5. Verify the completed integration

Before implementing the handoff, you can verify configuration and discovery:

1. Open <OIDC_ISSUER>/.well-known/openid-configuration. It should return JSON with the expected issuer and endpoints. The Next container must also be able to reach those HTTPS endpoints.
2. Check Settings → OIDC for the configured issuer and exact callback URL.
3. Confirm email/password login remains usable while integration is pending.

After the developer integration is complete:

1. Sign out, click Sign in with Authelia, and authenticate with Authelia.
2. Confirm the browser returns through the NextAuth callback to /pages.
3. Check /api/me through the web app and save a bookmark to confirm the session resolves to the intended local user and Go accepts its identity.
4. Sign out and back in to verify the same user and data are retained.
5. Test a new Authelia user, an explicitly linked existing account, and two different users to verify provisioning, account linking, and data isolation.

6. Troubleshooting

Symptom	Likely cause
Variables are set, but button is disabled	Expected in the current build: oidcReady remains false until section 4 is implemented
Config still says Not connected	One of the variables is empty or a placeholder, or containers were not recreated after editing .env
NextAuth returns AccessDenied	The current callbacks.signIn deliberately rejects Authelia; after integration, investigate identity mapping
Go callback returns 501	Expected stub; the browser callback must reach Next.js, not Go
Authelia shows "invalid redirect_uri"	Callback URL not listed exactly in redirect_uris
Error page ?error=Configuration after login	Wrong client secret (digest used instead of plain), or the issuer is unreachable or has an invalid TLS certificate
Required identity claims are missing	Check Authelia's claims policy and user profile
Browser has a session, but Go returns 401	Check that the session ID is the resolved local User.id, not the OIDC subject

7. Optional: Authelia-only login

Once the completed integration has been verified, decide whether to keep email/password login as a fallback. An Authelia-only deployment requires disabling the credentials provider, local login/signup screens, and local signup/login endpoints in both Next.js and Go, while preserving the trusted OIDC identity-provisioning path. Hiding the email form alone does not disable the backend password login routes.