baron-sso/docs/AGENTS.md

AGENTS 가이드 (Baron SSO)

목적

• 인증/인가 허브로서 Backend + Ory Stack 중심 아키텍처를 유지
• 사용자 플로우(UserFront)와 관리 플로우(Admin/DevFront)를 명확히 분리
• 네트워크/보안 경계를 문서화해 회귀/설정 오류를 방지

시스템 요약

• Backend: Command 단일 진입점, 감사 로그를 ClickHouse에 적재
• Ory Stack: Kratos/Hydra/Keto/Oathkeeper (인증/토큰/정책)
• Front: UserFront(Flutter)-사용자 접점, AdminFront/DevFront(React)-내부 관리도구
• 원칙: Front는 Backend API를 통해서만 IDP 기능을 호출

네트워크/보안 경계

• ory-net: Ory 내부 통신 전용 네트워크
• baron_net: App(backend/userfront/adminfront/devfront) 네트워크
• public_net: Oathkeeper, userfront 외부 공개. Gateway를 이용해 Proxy 분기

핵심 규칙:

• Ory Admin 포트는 외부 노출 금지 (Backend만 ory-net을 통해 접근)
• UserFront는 Oathkeeper 뒤에 있지 않음
• 모든 Front(User/Admin/Dev)는 Ory Admin 엔드포인트에 직접 접근하지 않음

인증/세션 핵심

• IDP_PROVIDER Ory 전용 저장 구조지만 향후 마이그레이션으로 추가 스택 지원할 수 있음
• sessionJwt는 JWT가 아닐 수 있음 (Kratos session token은 opaque 가능)
• OIDC Consent 플로우는 UserFront의 /consent 경로에서 처리
• 토큰/쿠키 전달 방식 변경 시 docs/auth-flow.md를 반드시 갱신

작업 체크리스트

• 인증/로그인 변경 시

  • docs/auth-flow.md 업데이트
  • 세션/쿠키/Authorization 전달 방식 영향도 점검
  • UserFront가 Ory/Oathkeeper 직접 호출하지 않도록 확인

• Ory 설정 변경 시

  • compose.ory.yaml, docker/ory/* 변경 범위 명시
  • ory-net/public_net 경계 유지 여부 확인

• 환경 변수 추가/변경 시

  • .env.sample 반영
  • 문서/가이드 갱신

• 배포/운영 변경 시

  • Makefile/compose 실행 절차 영향 확인
  • 최소 Smoke 테스트 수행

테스트 참고

• 테스트 계획 및 수동 실행 기준은 docs/test-plan.md를 따른다.