diff --git a/바론 SSO와 Ory Stack 연동 설명.md b/바론 SSO와 Ory Stack 연동 설명.md index 6329cae..3864cb2 100644 --- a/바론 SSO와 Ory Stack 연동 설명.md +++ b/바론 SSO와 Ory Stack 연동 설명.md @@ -1,76 +1,73 @@ -# 바론 SSO와 Ory Stack 연동 설명 +# 바론 SSO와 Ory 스택 — 팀원 대상 설명 --- -## 요약 -바론(Baron) SSO는 내부 서비스의 인증·인가를 통합하기 위해 Ory 생태계(예: Kratos, Hydra, Oathkeeper, Keto)를 활용합니다. 이 문서는 각 컴포넌트의 역할과 바론 SSO 내에서의 연관성, 통합 시 고려사항과 참조 파일 위치를 설명합니다. +## 목적(한 문장) +팀원이 빠르게 이해하고 통합 작업을 시작할 수 있도록 Ory 컴포넌트와 바론 SSO 연동 방식을 실무 관점에서 설명합니다. --- -## 핵심 컴포넌트와 역할 -- Kratos: 사용자 계정·인증(로그인, 비밀번호, 복구, 세션) 관리. 사용자 프로필과 인증 수단을 중앙에서 관리합니다. -- Hydra: OAuth2/OIDC 인증 서버로서 클라이언트(서비스)에 대해 토큰 발급, 클라이언트 등록, 동의(Consent) 처리를 담당합니다. -- Oathkeeper: 인증·인가 프록시(Edge)로서 요청을 검증하고 정책에 따라 서비스 접근을 허용/차단합니다. -- Keto (선택적): 권한 모델(ACL/정책) 저장소로서 세밀한 권한 결정을 지원합니다. +## 핵심 개념 (짧고 명확하게) +- Kratos: 사용자 계정·인증(로그인, 비밀번호, 세션)을 담당합니다. "누가 누구인지"를 관리합니다. +- Hydra: OAuth2/OIDC 토큰을 발급합니다. 서비스(클라이언트)가 인증을 위해 의존하는 엔진입니다. +- Oathkeeper: 서비스 앞단에서 토큰을 검사하고 요청을 허용/차단하는 프록시입니다. +- Keto(옵션): 세부 권한(ACL/정책) 판정을 외부에서 처리합니다. --- -## 바론 SSO에서의 구성 및 흐름(요약) -1. 사용자가 `userfront`/`adminfront` 같은 서비스에 접속하면 서비스는 Hydra로 OIDC 인증 요청을 보냅니다. -2. 사용자 인증은 Kratos(또는 외부 IdP)에서 수행됩니다. 인증 후 Kratos는 세션을 생성하고 필요한 ID 토큰/코드를 반환합니다. -3. Hydra가 토큰을 발급하면 서비스는 해당 토큰으로 사용자 세션을 구성합니다. -4. 서비스 앞단에 Oathkeeper를 배치하면, 토큰 검증·권한 확인·정책 시행을 중앙화할 수 있습니다. -5. 세부 권한 판단이 필요하면 Keto를 사용해 정책 기반 권한결정을 외부화합니다. +## 한눈에 보는 흐름 (개발자가 알아야 할 핵심 흐름) +1. 사용자가 `userfront` 같은 서비스에 접근합니다. +2. 서비스는 사용자에게 Hydra의 인증 페이지로 리디렉션합니다 (OIDC Authorization). +3. 실제 로그인(아이디/비밀번호, MFA)은 Kratos에서 수행되고 세션이 만들어집니다. +4. Kratos 인증 성공 후 코드가 Hydra로 돌아가고, Hydra는 토큰을 발급합니다. +5. 발급된 토큰으로 서비스가 사용자 세션을 구성하고 리소스에 접근합니다. +6. Oathkeeper가 앞단에 있으면 토큰 검증과 권한 시행은 중앙화됩니다. --- -## 바론 SSO와의 연계 포인트 -- 사용자 저장소: Kratos의 사용자 스키마를 바론의 사용자 모델에 맞춰 매핑(동기화 또는 온디맨드 매핑). -- 클라이언트 등록: 각 프론트엔드/백엔드 서비스는 Hydra에 `client_id`/`redirect_uri`를 등록해야 합니다. -- 토큰 검증: 서비스는 액세스 토큰 또는 ID 토큰을 검증해야 하며, Oathkeeper 사용 시 서비스 내 검증 로직을 단순화할 수 있습니다. -- 세션 정책: Kratos와 Hydra의 세션/토큰 수명 정책을 조직 정책에 맞게 조정합니다. +## 팀별 체크리스트 (쉽게 실행 가능한 항목) +- 개발팀: + - Hydra에 `client_id`/`redirect_uri` 등록 + - OIDC 라이브러리로 로그인 리디렉션/콜백 구현 + - 토큰(액세스/ID) 검증 구현 또는 Oathkeeper 사용 +- 보안팀: + - 토큰 만료·리프레시 정책 검토 + - TLS, 시크릿 관리 정책 점검 +- 운영팀: + - Ory 컴포넌트 모니터링(헬스체크, 로그 수집) + - 스테이징/프로덕션 분리 및 백업 절차 수립 --- -## 통합 시 권장 설정과 고려사항 -- 프로토콜: OIDC(OAuth2) 권장. SAML이 필요하면 별도 연동 고려. -- TLS: 모든 통신은 TLS(HTTPS)로 보호. -- 클라이언트 시크릿 관리: 시크릿은 시크릿 매니저(예: Vault) 또는 Docker/Kubernetes 시크릿으로 관리. -- 감사 로그: 로그인/토큰발급/권한변경 이벤트를 중앙 로그로 수집(ELK/Promtail 등). -- 환경 분리: 스테이징과 프로덕션에서 별도의 Ory 인스턴스와 클라이언트 등록을 유지. +## 빠른 통합 단계 (실무 명령형) +1. 로컬에서 스택 기동: `docker compose -f docker/compose.ory.yaml up` (환경변수 확인) +2. Kratos 사용자 스키마 확인 및 필요시 매핑 수정 +3. Hydra에 서비스 클라이언트 등록(redirect URI, grant types, scopes) +4. 프론트엔드에서 로그인 흐름 테스트(리디렉션 → 로그인 → 콜백) +5. Oathkeeper 정책을 적용해 서비스 접근 제어 검증 +6. 통합 테스트 케이스를 작성해 반복 검증 --- -## 레포지토리 내 참조 파일(예) -- Ory 관련 Compose 예시: [docker/compose.ory.yaml](docker/compose.ory.yaml) -- 루트의 Compose(또는 배포 템플릿): [compose.ory.yaml](compose.ory.yaml) -- 서비스 디렉터리 예: `userfront`, `adminfront`(각 서비스는 Hydra 클라이언트로 등록 필요) +## 데모/점검 체크리스트 (발표·검증용) +- 브라우저에서 서비스 접속 → SSO 로그인 흐름 정상 동작 확인 +- 토큰 클레임(`iss`, `aud`, `exp`)과 사용자 정보 정상 매핑 확인 +- Oathkeeper 사용 시, 인증 실패/권한 없음 케이스 확인 +- 로그(인증/토큰/권한 변경)가 중앙에 수집되는지 확인 --- -## 통합 단계(개발팀 가이드) -1. 로컬/스테이징에서 Ory 스택(kratos, hydra, oathkeeper 등)을 기동합니다. 예: `docker compose -f docker/compose.ory.yaml up`. -2. Kratos 사용자 스키마·마이그레이션을 검토하고 바론의 사용자 모델에 맞게 조정합니다. -3. Hydra에 서비스(클라이언트)를 등록(redirect URI, grant types, scopes). -4. 서비스 쪽에 OIDC 라이브러리 설정(로그인 리디렉션, 콜백 핸들링, 토큰 저장/검증). -5. Oathkeeper 정책을 만들어 서비스 앞단에서 인증·인가를 시행하도록 구성. -6. 통합 테스트: 로그인 → 리디렉션 → 토큰 발급 → 리소스 접근 플로우 검증. +## 레포지토리 참조(빠른 위치) +- Ory 관련 Compose 예시: [docker/compose.ory.yaml](docker/compose.ory.yaml) +- 루트 배포 템플릿: [compose.ory.yaml](compose.ory.yaml) +- 주요 서비스: `userfront`, `adminfront` (각 서비스는 Hydra 클라이언트로 등록 필요) --- -## 데모/점검 체크리스트 -- 로컬에서 SSO 로그인 흐름 시연 가능 여부 확인. -- 클라이언트 등록 정보와 리다이렉트 URI 일치 여부 확인. -- 토큰(액세스·ID)의 클레임(iss, aud, exp 등) 검증. -- 로그/감사 이벤트가 중앙에 수집되는지 확인. +## 다음 행동(권장) +1. 각 팀은 위의 체크리스트 항목 중 담당 항목 선택 후 담당자·일정 등록 +2. 내가 도와줄 수 있는 작업: 클라이언트 등록 샘플, `docker compose` 실행 가이드, 프레임워크별 코드 스니펫 제공 --- -## 참고 및 추가 자료 -- Ory 공식 문서: https://www.ory.sh/docs -- 리포지토리: 프로젝트 루트의 [README.md](README.md) 및 [docker/](docker/) 디렉터리 - - ---- - -작성자 노트: 필요하시면 이 문서에 실제 `docker compose` 예시, 환경변수 목록, 각 컴포넌트의 포트/엔드포인트 예시, 또는 서비스별 샘플 설정을 추가하겠습니다. +원하시면 이 문서에 실제 환경변수 목록, 포트/엔드포인트 예시, 또는 프레임워크별 코드 스니펫을 추가하겠습니다.