ADR-004: Built-in Auth System (내장 인증 시스템)
Status: Accepted | Date: 2026-02-10
맥락
Fascia로 구축된 백엔드에는 사용자 인증(authentication)과 인가(authorization)가 필요합니다. Fascia가 자체 인증 시스템을 제공할지, 외부 제공자(Firebase Auth, Auth0 등)와 연동할지, 아니면 인증을 전적으로 고객에게 맡길지가 문제입니다.
Fascia의 대상 사용자는 비개발자입니다. 외부 인증 제공자를 설정하고, OAuth 플로우를 관리하며, 토큰 검증을 API 엔드포인트에 연결하는 것은 상당한 진입 장벽입니다. 동시에 인증은 올바르게 구현해야 하는 보안 핵심 컴포넌트입니다.
결정
Fascia는 일급(first-class) Entity와 자동 생성 Tool로 구현된 내장 인증 시스템을 제공합니다. 인증 시스템은 다른 모든 비즈니스 로직과 동일한 Entity/Flow 패러다임을 따릅니다.
고객의 프로덕트 요구에 따라 세 가지 인증 모드를 지원합니다:
- Self-login (자체 로그인) -- 이메일/패스워드 회원가입 및 로그인, bcrypt 해싱과 JWT 토큰 사용.
- Social login (소셜 로그인) -- OAuth 2.0 제공자 (Google, Apple, Kakao, Naver, GitHub 등).
- Hybrid (하이브리드) -- 자체 로그인과 소셜 로그인을 동시에 지원하며, 이메일 주소가 일치할 때 자동 계정 연결.
핵심 인증 구성요소:
- User Entity -- 고객이 추가 필드로 확장할 수 있는 시스템 엔티티.
- AuthProvider Entity -- OAuth 2.0 제공자 설정 (클라이언트 ID, 스코프, 콜백 URL).
- RBAC -- 권한 매트릭스를 통한 역할 기반 접근 제어 (admin, staff, customer, 커스텀 역할).
- 행 수준 접근 제어 -- 실행 계약에 통합된 소유권 기반 데이터 필터링.
- JWT 생명주기 -- 액세스 토큰(단기) 및 리프레시 토큰(사용 시마다 로테이션).
검토한 대안
| 옵션 | 장점 | 단점 |
|---|---|---|
| 내장 인증 (선택됨) | Entity/Flow 모델과의 완벽한 통합, BYOC 준수, 고객이 모든 데이터 소유 | 보안 핵심 시스템을 직접 구축하고 유지해야 함 |
| 외부 전용 (Firebase Auth, Auth0) | 성숙하고 검증된 솔루션, 구축할 것이 적음 | 고객 데이터가 서드파티 서비스에 존재, BYOC 원칙 위반, 비개발자에게 설정 복잡 |
| 인증 없음 (BYO) | Fascia 구현이 가장 단순 | 비개발자에게 가장 큰 고충, 주요 기능 공백 |
결과
긍정적
- 일관된 패러다임 -- 인증도 비즈니스 로직과 동일한 Entity, Tool, Flow 개념으로 설계됩니다. 사용자가 별도의 시스템을 배울 필요가 없습니다.
- BYOC 준수 -- 모든 자격 증명, 토큰, 사용자 데이터가 고객의 자체 인프라에 저장됩니다. OAuth 클라이언트 시크릿은 고객의 Secret Manager에 들어갑니다.
- 커스터마이징 가능 -- 고객이 표준 Flow 에디터를 사용하여 인증 플로우를 확장할 수 있습니다 (이메일 인증 단계 추가, 커스텀 레이트 리미팅, MFA 등).
- 통합된 인가 -- RBAC와 행 수준 접근 제어가 모든 Tool 호출에 대해 실행 계약(Execution Contract)의 일부로 자동 적용됩니다.
부정적
- 개발 비용 -- 안전한 인증 시스템을 처음부터 구축하는 것은 상당한 투자입니다. 패스워드 해싱, 토큰 로테이션, OAuth 플로우, 계정 연결 모두 신중한 구현이 필요합니다.
- 지속적인 유지보수 -- OAuth 2.0 제공자 API는 시간이 지남에 따라 변경됩니다. 지원하는 소셜 제공자가 늘어날수록 유지보수 부담이 증가합니다.
- 보안 책임 -- 인증 시스템의 버그는 모든 고객에게 영향을 미칩니다. 프로덕션 릴리스 전에 인증 구현에 대한 보안 감사가 필수입니다.
리스크
- 인증 시스템은 실제 사용자 데이터를 다루는 프로덕션 환경에서 사용되기 전에 전문적인 보안 감사를 받아야 합니다.
- OAuth 제공자 API 변경(새로운 스코프, 폐기된 엔드포인트, 정책 변경)에 대한 지속적인 모니터링과 업데이트가 필요합니다.