baron-sso/docs/kratos-integration-report.md

Ory Kratos 인증 엔진 전환 작업 보고서

1. 개요

기존 Descope SaaS 기반 인증 시스템을 자가 호스팅(Self-hosted) IDP인 Ory Kratos로 전환하고, 이를 백엔드(Go Fiber)와 연동하는 작업을 수행하였습니다.

2. 주요 작업 내용

2.1 인프라 및 SDK 설정

• SDK 설치: Ory Kratos Go SDK (github.com/ory/kratos-client-go)를 백엔드 프로젝트에 추가.
• 클라이언트 초기화: AuthHandler 내부에 Kratos Public API 통신을 위한 API Client 주입 및 환경 변수 연동.

2.2 인증 Flow 핸들러 구현 (auth_handler.go)

Ory Kratos의 API-first 방식(Native Flow)에 맞춘 신규 핸들러 구현:

• InitializeLoginFlow: 로그인 프로세스 시작을 위한 flow_id 발급 API.
• InitializeRegistrationFlow: 회원가입 프로세스 시작을 위한 flow_id 발급 API.
• LoginSubmit: 사용자의 ID/PW를 Kratos에 제출하고 성공 시 세션 쿠키를 클라이언트에 전달.
• RegistrationSubmit: 커스텀 Traits(사용자 정보)와 비밀번호를 Kratos에 전달하여 계정 생성.

2.3 라우팅 설정 (main.go)

신규 인증 엔진을 위한 전용 엔드포인트 그룹 등록:

• GET /api/v1/auth/ory/login/initialize
• POST /api/v1/auth/ory/login/submit
• GET /api/v1/auth/ory/registration/initialize
• POST /api/v1/auth/ory/registration/submit

2.4 보안 및 감사 (Security & Audit)

• 세션 관리: Kratos에서 발급한 Set-Cookie 헤더를 추출하여 클라이언트에 투명하게 전달(Pass-through).
• 감사 로그: 로그인 시도 및 성공 시 시각, IP, 대상 아이디 등을 ClickHouse 감사 로그 시스템에 기록.
• 타입 오류 해결: Kratos SDK의 구조체 타입 미스매치 이슈 해결(result.Session nil 비교 로직 수정).

3. 향후 과제 (Next Steps)

1. UI 연동: userfront (Flutter)의 API 엔드포인트를 기존 Descope에서 신규 Ory 경로로 전환.
2. 계정 복구: 비밀번호 찾기(Recovery) 및 이메일 확인(Verification) Flow 추가 연동.
3. 관리자 기능: adminfront에서 Kratos Identities를 직접 조회/삭제하는 관리 API 연결.