ADR-007: Logto for Authentication

Date: 2024-02-01 Status: Accepted

Context

LumiBase needs an authentication solution supporting:

1. Multi-tenancy — different sites have different users; an admin@siteA.com must not be able to access Site B
2. OIDC/OAuth2 — standard protocols for SSO integration with enterprise identity providers (Google Workspace, Microsoft Entra, Okta)
3. Invitation flow — admins invite users by email; users set their password via a signed link
4. Self-hosted option — for Docker deployments, auth cannot depend on a third-party SaaS that may be unavailable
5. Lightweight — should not require a heavy auth server in Cloudflare Workers mode

Options considered:

• Supabase Auth — PostgreSQL-coupled, not easily multi-tenant per-site
• Auth.js (NextAuth) — React/Next.js focused, not suitable for a standalone Hono API
• Keycloak — very heavy, Java-based, not Docker-friendly for small self-hosted setups
• Logto — OIDC-native, multi-tenant, open-source, Docker-deployable, minimal footprint
• Custom JWT — maximum control but significant implementation burden (MFA, PKCE, token rotation, etc.)

Decision

Use Logto as the primary authentication provider.

Integration pattern:

• Logto issues JWTs with standard OIDC claims
• apps/cms validates JWTs at the edge using JWKS (/.well-known/jwks.json from Logto), cached via CacheProvider
• User metadata (site assignments, roles, capabilities) is stored in LumiBase's own users table, linked by Logto subject (sub) claim
• The withAuth() middleware validates the JWT and loads the LumiBase user row into context

For Docker self-hosted: Logto runs as a Docker container alongside LumiBase CMS. For Cloudflare Workers: Logto Cloud (or a self-hosted Logto instance) is used.

SCIM 2.0 provisioning (for enterprise SSO) uses a separate SCIM_TOKEN — not the Logto JWT pipeline.

Consequences

Positive:

• Standard OIDC JWT validation — no Logto SDK required in the hot path; just JWKS + JWT verification
• Multi-tenant organization support via Logto Organizations feature
• Open source under Apache 2.0 — self-hostable without vendor lock-in
• Handles secure token rotation, refresh tokens, and PKCE out of the box

Negative:

• An additional service to deploy and maintain (Logto container in Docker mode)
• Logto's multi-tenant model may not perfectly map to LumiBase's site-level isolation — requires careful configuration of Organizations
• Migration from another auth provider requires re-issuing all tokens

Neutral:

• LOGTO_ENDPOINT and LOGTO_APP_ID are required environment variables for both deployment modes