forked from baron/baron-sso
34dba6689c
- replace local auth and test-plan references with wiki URLs - delete duplicated local markdown files now covered by wiki - keep operational docs pointing to the new wiki pages
67 lines
3.5 KiB
Markdown
67 lines
3.5 KiB
Markdown
# AGENTS 가이드 (Baron SSO)
|
|
|
|
## 버그 수정 절차 대원칙 (강제)
|
|
- 버그 대응 시 **재현 테스트를 먼저 작성**합니다.
|
|
- 재현 테스트가 실패하는 상태를 확인한 뒤에만 수정 작업을 시작합니다.
|
|
- 수정 후에는 테스트를 반복 실행하여 재현 테스트가 안정적으로 통과할 때까지 계속 보완합니다.
|
|
- 재현 테스트 없이 “감으로 수정”하거나, 실패 테스트를 남긴 채 성공으로 보고하지 않습니다.
|
|
- 이슈 종료 전에는 최소 1회 이상 실제 사용자 경로(예: 로그인/새로고침/리다이렉트)를 확인합니다.
|
|
- 테스트/원인/조치 내역은 문서(`docs/test-plan/*`, `docs/trouble-shooting/*`)에 반영합니다.
|
|
|
|
## 목적
|
|
- 인증/인가 허브로서 **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` 경로에서 처리
|
|
- 토큰/쿠키 전달 방식 변경 시 `https://gitea.hmac.kr/baron/baron-sso/wiki/Authentication-and-Login-Flow.-`를 반드시 갱신
|
|
|
|
## 작업 체크리스트
|
|
- 인증/로그인 변경 시
|
|
- `https://gitea.hmac.kr/baron/baron-sso/wiki/Authentication-and-Login-Flow.-` 업데이트
|
|
- 세션/쿠키/Authorization 전달 방식 영향도 점검
|
|
- UserFront가 Ory/Oathkeeper 직접 호출하지 않도록 확인
|
|
|
|
- Ory 설정 변경 시
|
|
- `compose.ory.yaml`, `docker/ory/*` 변경 범위 명시
|
|
- `ory-net`/`public_net` 경계 유지 여부 확인
|
|
|
|
- 환경 변수 추가/변경 시
|
|
- `.env.sample` 반영
|
|
- 문서/가이드 갱신
|
|
- 클라이언트 로그 정책 영향 확인 (`CLIENT_LOG_DEBUG`, `USERFRONT_DEBUG_LOG`)
|
|
|
|
- 배포/운영 변경 시
|
|
- `Makefile`/compose 실행 절차 영향 확인
|
|
- 최소 Smoke 테스트 수행
|
|
- 로그 수집 레벨이 운영 기본 정책(`WARN/ERROR`)을 유지하는지 확인
|
|
|
|
## 클라이언트 로그 정책
|
|
- 상세 정책은 `docs/client-log-policy.md`를 기준으로 유지합니다.
|
|
- 원칙:
|
|
- 운영 기본값은 `WARN/ERROR`만 수집
|
|
- 운영 디버그는 `CLIENT_LOG_DEBUG=true`로만 일시 허용
|
|
- 민감정보 마스킹은 환경과 무관하게 항상 적용
|
|
|
|
## 테스트 참고
|
|
- 테스트 계획 및 수동 실행 기준은 `https://gitea.hmac.kr/baron/baron-sso/wiki/Test-Plan-and-Principles.-`를 따른다.
|