본문으로 건너뛰기

KR Kakao 인증 비즈니스 규칙

1. 컨텍스트 맵 및 협력 전략​

  • RegionalAuthKR 컨텍스트는 Auth Core와 Conformist 관계를 유지한다. JWT 발급 규칙, 토큰 스키마, 이벤트 명명은 공통 규칙을 그대로 적용한다.
  • Kakao OAuth 서버와는 Anticorruption Layer 정책을 적용해 외부 DTO를 내부 Value Object로 즉시 변환하고, 오류 코드를 도메인 예외로 매핑한다.
  • User Profile, Notification, Analytics 도메인에는 ExternalAuthLinked, ExternalAuthUnlinked, UserProvisionRequired 통합 이벤트를 발행해 느슨한 결합을 유지한다.

2. 인증 흐름 규칙​

  1. InitiateKakaoAuthCommand는 반드시 state, nonce, requestedScopes를 생성하고 TimeMachine 기준 expireAt을 설정한다.
  2. state/nonce는 Redis auth:kr:kakao:session:{sessionId} 키에 TTL과 함께 저장되어야 하며, 만료 시 정리 워커가 KakaoAuthSessionExpiredEvent를 발행한다.
  3. CompleteKakaoAuthCommand는 state 검증이 성공한 경우에만 Kakao 토큰 엔드포인트에 접근할 수 있다.
  4. Kakao API에서 반환한 사용자 ID는 KakaoUserId Value Object로 변환되며, 원문 문자열은 영구 보관하지 않는다.
  5. 동일한 KakaoUserId가 다른 사용자 계정에 연결되려 하면 KakaoIdentityAlreadyLinkedError를 발생시키고 연결을 차단한다.
  6. 토큰 갱신은 만료 5분 전 한 번만 시도하며 실패 시 SessionExpiredEvent와 알림 이벤트를 발행해 재로그인을 유도한다.

3. 보안 및 규제 규칙​

  • Kakao 앱 키는 플랫폼별로 분리된 값을 사용한다. REST OAuth 호출은 서버 시크릿(AUTH_OAUTH_KAKAO_CLIENT_ID 등)으로 관리되는 REST API 키만 사용하고, 모바일(Android/iOS) “카카오로 로그인하기” 버튼은 네이티브 앱 키만 사용해야 하며 서로 공유하거나 하드코딩해서는 안 된다.
  • OAuth 토큰, state, nonce는 암호화된 Redis 네임스페이스(auth:kr:kakao:*)에 저장하고, PII가 포함된 이벤트에는 마스킹을 적용한다.
  • 사용자의 명시적 동의 없이 Kakao 프로필 데이터를 영구 저장하지 않는다. 동의 철회 이벤트 수신 시 즉시 연결을 해제하고 토큰을 폐기한다.
  • Kakao 오류 코드는 다음 도메인 예외로 매핑된다.
    Kakao 오류도메인 예외설명
    KOE320 (만료된 authorization code)KakaoAuthorizationCodeExpiredError사용자 재로그인 필요
    KOE303 (인증 실패)KakaoAuthenticationFailedError재시도 가능
    기타 5xxKakaoProviderUnavailableErrorCircuit Breaker 트리거
  • 모든 감사 로그는 TimeMachine에서 제공하는 권한 있는 시각을 포함해야 하며, 토큰과 state는 30일 이내에 비식별화 프로세스를 거쳐야 한다.

4. 이벤트 및 일관성 규칙​

  • KakaoAuthSessionCreatedEvent는 KakaoAuthSession Aggregate가 Redis 저장을 완료했음을 의미하며, 1분 이내 콜백이 없으면 만료 워커가 KakaoAuthSessionExpiredEvent를 발행한다.
  • KakaoAuthCompletedEvent 발행 전에 JWT 발급, ExternalIdentity 연결, 감사 로그 기록이 모두 성공해야 하며 실패 시 전체 플로우를 롤백한다.
  • 이벤트 발행은 AuthEventPublisher를 통해 수행되며, Redis idempotency 키(auth:kr:kakao:idempotency:{state})가 존재하면 재발행을 중단한다.
  • 모든 Timestamp는 TimeMachine 기반이어야 하며, 시스템 시계를 직접 호출해서는 안 된다.

5. 운영 및 모니터링 규칙​

  • Feature flag(feature.auth.kakao)가 비활성화된 경우 Kakao 관련 REST 라우트와 이벤트 핸들러를 등록하지 않는다.
  • Kakao API 장애가 15분 이상 지속되면 자동으로 feature flag를 비활성화하고 폴백 로그인 방식을 안내한다.
  • Prometheus 지표 auth_kakao_login_latency_seconds, auth_kakao_login_failure_total을 최소 1분 간격으로 수집하고, Alertmanager에 임계값(예: 실패율 5% 이상)을 설정한다.
  • 장애 대응 이후에는 UserProvisionRequiredEvent backlog를 확인해 누락된 사용자 프로비저닝이 없는지 검증한다.