본문으로 건너뛰기

KR Kakao 인증 도메인 개요

1. 소개​

KR Kakao 인증 도메인은 한국 지역 서비스를 대상으로 Kakao OAuth 2.0을 통합하는 RegionalAuthKR 바운디드 컨텍스트입니다. 공통 인증(Core Auth) 도메인과 협력하여 JWT 액세스/리프레시 토큰 발급, 외부 식별자 연동, 이벤트 브로드캐스트를 담당하며, 지역 정책·규제 요구사항을 충족시키는 것을 목표로 합니다.

2. 폴더 구조​

  • business-rules.md – 비즈니스 정책 및 제약 정의
  • bounded-context.md – 컨텍스트 경계 및 협력 전략
  • domain-model.md – Aggregate, Entity, Value Object, 서비스 책임
  • endpoints.md – REST 엔드포인트 계약 및 오류 코드
  • event-storming.md – 명령/이벤트 흐름과 시퀀스 분석
  • architecture.md – 모듈 토폴로지와 Kakao 로그인 기술 구조
  • overview.md – 도메인 개요(본 문서)
  • requirements.md – 기능/비기능/규제 요구사항 정리
  • (공통 참조) apps/dta-wi-doc/docs/domains/common/core-domains/auth/ – 공통 인증 구조 및 기술 문서

기술 구현 상세는 본 디렉터리의 architecture.md와 공통 인증 문서(architecture.md, implementation-plan.md, technical-docs/)를 함께 참고하세요.

3. 유비쿼터스 언어​

  • KakaoAuthSession: Kakao 인가 플로우 동안 유지되는 state/nonce 세션 Aggregate.
  • ExternalIdentityLink: 외부 공급자(Kakao)와 내부 사용자 ID 간 연결.
  • KakaoUserId: Kakao에서 제공하는 회원 식별자(암호화·마스킹 대상).
  • InitiateKakaoAuthCommand / CompleteKakaoAuthCommand: 인가 플로우를 제어하는 명령.
  • ExternalAuthLinkedEvent / UserProvisionRequiredEvent: 사용자 연결 결과를 나타내는 도메인/통합 이벤트.
  • Anticorruption Layer (ACL): Kakao OAuth API를 감싸는 HTTP 클라이언트 계층.
  • TimeMachine: 가상 시계를 제공하는 공용 서비스. 토큰 만료 계산, 감사 로그에 사용.

4. 주요 기능​

  1. Kakao OAuth 2.0 인가 URL 생성 및 state/nonce 보관.
  2. Kakao authorization code 교환 및 액세스/리프레시 토큰 수신.
  3. Kakao 사용자 ID와 내부 사용자 계정 연결·재연결·해제.
  4. 공통 인증(Core Auth)과 협력하여 JWT 액세스/리프레시 토큰을 발급.
  5. 외부 도메인(Analytics, Notification 등)으로 인증 이벤트 발행.
  6. Redis 기반 idempotency 키를 활용한 콜백 중복 처리 방지.

상세 요구사항은 요구사항 명세서를 참조하세요.

5. 핵심 정책 및 규칙​

  • 모든 state/nonce는 TimeMachine 기준 만료 시각(expireAt)과 함께 Redis에 저장해야 합니다.
  • 동일한 Kakao 사용자 ID는 동시에 두 개의 내부 계정에 연결될 수 없습니다.
  • Kakao API 장애 시 Circuit Breaker를 적용하고, 3회 이상 연속 실패 시 feature flag를 통해 폴백합니다.
  • 모든 이벤트·로그에는 TimeMachine 기반 권한 있는 시각을 사용합니다.
  • Kakao 앱 키는 플랫폼별로 분리 관리합니다. 백엔드 REST OAuth 호출은 REST API 키만 사용하고, 모바일 앱 SDK 초기화(“카카오로 로그인하기” 버튼)는 네이티브 앱 키를 사용하며 서로 교차 사용하지 않습니다.

전체 정책 목록은 비즈니스 규칙에 있습니다.

6. 인증 흐름 (요약)​

  1. 인가 요청 – InitiateKakaoAuthCommand 실행, KakaoAuthSession 생성.
  2. 코드 교환 – Kakao 콜백 수신 후 ACL HTTP 클라이언트로 토큰 교환.
  3. 사용자 링크 – LinkKakaoIdentityCommand 실행, ExternalIdentityLink Aggregate 갱신.
  4. JWT 발급 – Auth Core의 IssueSessionService를 호출해 서버 세션 대신 JWT를 발급하고 KakaoAuthCompletedEvent를 발행.
  5. 이벤트 연동 – ExternalAuthLinkedEvent 등 통합 이벤트를 다운스트림 도메인에 전달.

플로우 상세와 브랜치는 이벤트 스토밍을 참고하세요.

7. 컨텍스트 경계​

항목설명
Bounded ContextRegionalAuthKR (Core Auth 하위 서브도메인)
업스트림Kakao OAuth 서버 – 외부 컨텍스트, Anticorruption Layer 적용
다운스트림Auth Core, User Profile, Notification, Analytics
협력 전략Auth Core와 Conformist, Kakao API와 ACL, 외부 도메인과 이벤트 기반 통합

Context Map 및 관계 상세는 비즈니스 규칙 1장과 이벤트 스토밍 다이어그램에 포함되어 있습니다.

8. 도메인 이벤트​

  • KakaoAuthSessionCreatedEvent
  • KakaoAuthCompletedEvent
  • ExternalAuthLinkedEvent
  • ExternalAuthUnlinkedEvent
  • KakaoProviderUnavailableEvent
  • UserProvisionRequiredEvent

각 이벤트의 트리거와 페이로드는 도메인 모델 3장에 정의되어 있습니다.

9. 사용자 유형 및 액터​

  • End User (Patient/App 사용자): Kakao 로그인을 통해 JWT 발급을 요청.
  • Internal Operator: 고객 지원을 위해 계정 연결/해제, 감사 로그 확인.
  • Background Worker: TTL 만료 처리, 토큰 갱신, 중복 콜백 정리.
  • External Systems: Notification, Analytics, CRM 등 이벤트 소비자.

액터별 권한 및 제약은 비즈니스 규칙 4장에서 확인할 수 있습니다.

10. 모니터링 및 감사​

  • 메트릭: auth_kakao_login_latency_seconds, auth_kakao_login_failure_total.
  • 로그 태그: event=kakao_auth, stage=request|callback|unlink, correlationId.
  • 감사 항목: state 생성/검증, 사용자 연결/해제, 토큰 갱신 실패.

모니터링 정책은 비즈니스 규칙 5장, API 응답 스키마는 엔드포인트 4장에서 정의됩니다.

11. 핵심 요구사항 요약​

  • Kakao OAuth 2.0 Authorization Code Grant 준수.
  • state/nonce TTL 10분, Redis 저장 필수.
  • TimeMachine 기반 JWT 만료 계산.
  • Redis idempotency 키로 중복 콜백 차단.
  • 4초 이하 왕복 지연(95 percentile) 성능 목표.

세부 사항과 Acceptance Criteria는 요구사항 명세서를 확인하세요.

12. 관련 문서​

13. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-10-20bok@weltcorp.com초기 Kakao 인증 구조 정리