ADR-004: Built-in Auth System
Status: Accepted | Date: 2026-02-10
Context
Backends built with Fascia need user authentication and authorization. The question is whether Fascia should provide its own auth system, integrate with external providers (like Firebase Auth or Auth0), or leave authentication entirely to the customer.
Fascia's target users are non-developers. Configuring external auth providers, managing OAuth flows, and wiring token validation into API endpoints is a significant barrier. At the same time, authentication is a security-critical component that must be implemented correctly.
Decision
Fascia provides a built-in authentication system implemented as first-class Entities and auto-generated Tools. The auth system follows the same Entity/Flow paradigm as all other business logic.
Three authentication modes are supported based on the customer's product needs:
- Self-login -- Email/password registration and login with bcrypt hashing and JWT tokens.
- Social login -- OAuth 2.0 providers (Google, Apple, Kakao, Naver, GitHub, and others).
- Hybrid -- Both self-login and social login simultaneously, with automatic account linking when email addresses match.
Core auth components:
- User Entity -- A system entity that customers can extend with additional fields.
- AuthProvider Entity -- OAuth 2.0 provider configuration (client ID, scopes, callback URLs).
- RBAC -- Role-based access control with a permission matrix (admin, staff, customer, custom roles).
- Row-level access control -- Ownership-based data filtering integrated into the Execution Contract.
- JWT lifecycle -- Access tokens (short-lived) and refresh tokens (rotated on each use).
Alternatives Considered
| Option | Pros | Cons |
|---|---|---|
| Built-in auth (chosen) | Seamless integration with Entity/Flow model, BYOC compliant, customer owns all data | Must build and maintain a security-critical system |
| External only (Firebase Auth, Auth0) | Mature, battle-tested, less to build | Customer data in third-party service, breaks BYOC principle, configuration complexity for non-devs |
| No auth (BYO) | Simplest for Fascia to implement | Biggest pain point for non-developers, major feature gap |
Consequences
Positive
- Consistent paradigm -- Auth is designed using the same Entity, Tool, and Flow concepts as business logic. Users do not need to learn a separate system.
- BYOC compliant -- All credentials, tokens, and user data are stored in the customer's own infrastructure. OAuth client secrets go into the customer's Secret Manager.
- Customizable -- Customers can extend auth flows (add email verification steps, custom rate limiting, MFA) using the standard Flow editor.
- Integrated authorization -- RBAC and row-level access control are automatically enforced as part of the Execution Contract for every Tool invocation.
Negative
- Development effort -- Building a secure auth system from scratch is a significant investment. Password hashing, token rotation, OAuth flows, and account linking all require careful implementation.
- Ongoing maintenance -- OAuth 2.0 provider APIs change over time. Each supported social provider adds a maintenance burden.
- Security responsibility -- Bugs in the auth system affect all customers. The auth implementation must undergo security auditing before production release.
Risks
- The auth system must be professionally audited before any customer uses it in production with real user data.
- OAuth provider API changes (new scopes, deprecated endpoints, policy changes) require ongoing monitoring and updates.