본문으로 건너뛰기

KR Kakao 인증 아키텍처

1. 모듈 토폴로지​

  • libs/feature/auth: 공통 인증 기능. OAuth 공급자 레지스트리, 세션/토큰 발급, Prisma 기반 저장소를 제공한다.
  • libs/feature/auth-kr: 지역 확장 모듈. Kakao OAuth 흐름, Circuit Breaker, 아이덴티티 링크 정책을 캡슐화한다.
  • libs/core/http-kakao: Kakao REST API용 ACL 클라이언트. 에러 표준화와 재시도 정책을 담당한다.
  • libs/core/redis: Redis 커넥션 및 고수준 유틸을 제공한다. state/nonce, idempotency 키, 아이덴티티 매핑에 활용한다.
  • libs/shared/contracts-auth: OAuth 콜백 이벤트 및 토큰 스펙을 정의한다.
  • libs/shared/contracts-time-machine-wir: TimeMachine 쿼리/응답 계약. 만료 시각 계산 시 필수.

설계 원칙: 지역 모듈(auth-kr)은 인프라를 직접 관리하지 않고, 가능한 한 공통 모듈(auth, core-*, shared-*)을 통해 책임을 분산한다.

2. Kakao 로그인 시퀀스​

3. 책임 분리​

  • 컨트롤러 계층 (feature/auth): HTTP 엔드포인트에서 OAuth 플로우를 시작하고 콜백을 수신한다.
  • 프로바이더 계층 (feature/auth-kr/KakaoAuthProvider): Kakao 전용 state 관리, 토큰 교환, Circuit Breaker, idempotency 제어를 담당한다.
  • 세션/토큰 발급 (feature/auth/IssueSessionService): 인증 완료 후 JWT 및 세션 리소스를 생성하고 Prisma 저장소에 기록한다.
  • 아이덴티티 링크 (feature/auth-kr/KakaoIdentityLinkService): Kakao 사용자 ID와 내부 사용자 ID를 Redis에 저장하고 충돌을 방지한다.
  • 이벤트 브로커 (EventEmitter2 + shared-contracts-auth): KakaoAuthCompletedEvent, ExternalAuthLinkedEvent 등을 발행하여 Notification·Analytics 등 다운스트림 도메인과 통합한다.

4. 데이터 저장 전략​

  • Redis:
    • auth:kr:kakao:session:*: state/nonce, redirect URI, 만료 시각을 TTL과 함께 저장.
    • auth:kr:kakao:idempotency:*: OAuth 콜백 중복 방지를 위한 dedupe 키.
    • auth:kr:kakao:identity:*: Kakao 사용자 ID ↔ 내부 사용자 ID 매핑.
    • auth:kr:kakao:pending:*: 신규 사용자 프로비저닝 대기 큐.
  • Prisma (RDB):
    • refreshToken, session: 세션 토큰과 리프레시 토큰 보관 (PrismaAuthRepository).
    • device, userRegistration: 디바이스 정보, 가입 기록 저장.

Redis는 고속 상태 관리와 중복 제어에, RDB는 장기 영속성과 규제 준수 데이터 보관에 사용한다.

5. TimeMachine 연동​

  • KakaoAuthProvider와 CompleteKakaoAuthService는 GetSystemTimeMachineCurrentTimeQuery를 통해 권한 있는 시각을 조회한다.
  • TimeMachine 비가용 시에는 로컬 시간을 사용하되 경고 로그를 남긴다.
  • 발급된 토큰의 만료 시각, 이벤트 타임스탬프는 모두 TimeMachine 기준을 따른다.

6. 확장 고려사항​

  • 추가 공급자: 동일 패턴으로 AuthProviderRegistry에 등록하면 다른 지역/공급자 확장을 지원한다.
  • 다중 이벤트 채널: AUTH_INTERNAL_EVENT_CHANNELS에 신규 채널을 추가해도 Redis 키 스킴과 충돌하지 않는다.
  • Rate Limiting: Kakao API 한도 초과 시 KakaoAuthCircuitBreakerService에서 trip을 발생시키고 Admin 알림을 발행하도록 확장 가능하다.
  • 프로비저닝 자동화: KakaoIdentityLinkService.markProvisionRequired 이벤트를 수신하는 워커를 추가하여 신규 사용자 계정 생성을 자동화할 수 있다.

7. 관련 문서 및 코드​

  • 도메인 흐름: event-storming.md
  • 비즈니스 규칙: business-rules.md
  • 공통 인증 아키텍처: apps/dta-wi-doc/docs/domains/common/core-domains/auth/architecture.md
  • 구현 코드: libs/feature/auth, libs/feature/auth-kr, libs/core/http-kakao