forked from baron/baron-sso
141 lines
6.3 KiB
Markdown
141 lines
6.3 KiB
Markdown
# Ory Stack 사용 가이드
|
|
|
|
이 문서는 Baron SSO 로컬/도메인 환경에서 Ory Stack(Kratos/Hydra/Keto/Oathkeeper) 사용법과 내부/외부 엔드포인트 구성을 정리합니다.
|
|
|
|
## 1) 구성 요약
|
|
- **Kratos**: Identity/Session 관리(SoT)
|
|
- **Hydra**: OAuth2/OIDC 토큰 엔진
|
|
- **Keto**: 권한/정책
|
|
- **Kratos UI**: UserFront가 self-service UI 역할 (login/registration 등)
|
|
|
|
## 2) 실행 방법
|
|
```bash
|
|
# 인증 리다이렉트 설정 생성/검증
|
|
make validate-auth-config
|
|
|
|
# 인프라 + Ory Stack
|
|
docker compose -f compose.infra.yaml -f compose.ory.yaml up -d
|
|
|
|
# 앱 스택(backend/userfront/adminfront/devfront)
|
|
docker compose -f docker-compose.yaml up -d
|
|
```
|
|
|
|
Make 기반 실행을 사용할 경우:
|
|
```bash
|
|
make up-ory
|
|
make up-app
|
|
```
|
|
`up-*` 타깃은 내부적으로 `validate-auth-config`를 선행 수행하여 callback/allowed_return_urls 정합성을 먼저 검증합니다.
|
|
|
|
## 3) 내부 통신 vs 브라우저 접근용 URL 분리
|
|
Ory 구성은 **컨테이너 내부 통신 URL**과 **브라우저 접근 URL**을 분리해야 합니다.
|
|
|
|
### 내부 통신용 URL(컨테이너 네트워크)
|
|
- `KRATOS_PUBLIC_URL=http://kratos:4433`
|
|
- `KRATOS_ADMIN_URL=http://kratos:4434`
|
|
- `HYDRA_ADMIN_URL=http://hydra:4445`
|
|
- Hydra public upstream은 Oathkeeper rule 내부에서 `http://hydra:4444`로 전달합니다.
|
|
|
|
### 브라우저 접근용 URL(외부 도메인/프록시)
|
|
- `KRATOS_BROWSER_URL` : Kratos Public의 외부 URL. 보통 `${OATHKEEPER_PUBLIC_URL}/auth`
|
|
- `KRATOS_UI_URL` : UserFront의 외부 URL (Kratos UI 역할)
|
|
- `HYDRA_PUBLIC_URL` : Hydra issuer/OIDC discovery의 외부 URL. 보통 `${OATHKEEPER_PUBLIC_URL}/oidc`
|
|
- `VITE_OIDC_AUTHORITY` : 프론트엔드 OIDC authority. `HYDRA_PUBLIC_URL`과 같아야 합니다.
|
|
|
|
예시(로컬):
|
|
```env
|
|
KRATOS_BROWSER_URL=http://localhost:4433
|
|
KRATOS_UI_URL=http://localhost:5000
|
|
```
|
|
|
|
예시(리버스 프록시/도메인):
|
|
```env
|
|
OATHKEEPER_PUBLIC_URL=https://sso.example.com
|
|
KRATOS_BROWSER_URL=https://sso.example.com/auth
|
|
KRATOS_UI_URL=https://sso.example.com
|
|
HYDRA_PUBLIC_URL=https://sso.example.com/oidc
|
|
VITE_OIDC_AUTHORITY=https://sso.example.com/oidc
|
|
```
|
|
|
|
### 포트 노출 정책
|
|
- **Kratos/Hydra Admin 포트는 호스트에 노출하지 않음** (내부 네트워크 전용)
|
|
- MCP 서버는 동일 네트워크에서 `http://kratos:4434`, `http://hydra:4445`로 접근
|
|
- Backend는 `ory-net`에 연결되어 있어 Admin 포트 접근 가능
|
|
- 브라우저/Frontend는 Backend API를 통해서만 IDP 기능을 호출
|
|
|
|
## 4) Kratos Self-service UI 리다이렉트 설정
|
|
Kratos는 self-service UI URL을 설정값으로 사용합니다. **UserFront의 브라우저 접근 URL**이어야 정상 동작합니다.
|
|
|
|
- `KRATOS_SELFSERVICE_DEFAULT_BROWSER_RETURN_URL`
|
|
- `KRATOS_SELFSERVICE_ALLOWED_RETURN_URLS`
|
|
- `KRATOS_SELFSERVICE_FLOWS_*_UI_URL`
|
|
- `KRATOS_ALLOWED_RETURN_URLS_JSON`
|
|
|
|
compose에서 기본적으로 다음과 같이 오버라이드합니다:
|
|
- `KRATOS_SELFSERVICE_FLOWS_LOGIN_UI_URL=${KRATOS_UI_URL}/login`
|
|
- `KRATOS_SELFSERVICE_FLOWS_REGISTRATION_UI_URL=${KRATOS_UI_URL}/registration`
|
|
- `KRATOS_SELFSERVICE_FLOWS_SETTINGS_UI_URL=${KRATOS_UI_URL}/error?error=settings_disabled` (임시 비활성)
|
|
- `KRATOS_SELFSERVICE_FLOWS_RECOVERY_UI_URL=${KRATOS_UI_URL}/recovery`
|
|
- `KRATOS_SELFSERVICE_FLOWS_VERIFICATION_UI_URL=${KRATOS_UI_URL}/verification`
|
|
|
|
stage/prod에서는 `KRATOS_ALLOWED_RETURN_URLS_JSON`에 공개 도메인과 callback/locale 경로를 명시합니다.
|
|
|
|
필수 후보:
|
|
- `${KRATOS_UI_URL}`, `${KRATOS_UI_URL}/`
|
|
- `${USERFRONT_URL}`, `${USERFRONT_URL}/`
|
|
- `${USERFRONT_URL}/ko`, `${USERFRONT_URL}/ko/`
|
|
- `${USERFRONT_URL}/en`, `${USERFRONT_URL}/en/`
|
|
- `${USERFRONT_URL}/auth/callback`
|
|
- `${USERFRONT_URL}/ko/auth/callback`
|
|
- `${USERFRONT_URL}/en/auth/callback`
|
|
- `${ADMINFRONT_CALLBACK_URLS}`, `${DEVFRONT_CALLBACK_URLS}`, `${ORGFRONT_CALLBACK_URLS}`
|
|
|
|
## 5) `/oidc` Gateway/Oathkeeper 책임 경계
|
|
Gateway는 `/oidc` prefix를 rewrite하지 않습니다. `/oidc/*` 요청은 prefix를 보존한 채 Oathkeeper로 전달하고, Oathkeeper rule이 `strip_path=/oidc`로 Hydra 내부 upstream(`http://hydra:4444`)에 전달합니다.
|
|
|
|
이 정책은 `gateway/nginx.conf`, `deploy/templates/gateway/nginx.conf`, `docker/ory/oathkeeper/rules*.json`, `docker/staging_pull_compose.template.yaml`에서 동일해야 합니다.
|
|
|
|
## 6) Oathkeeper active rules
|
|
Oathkeeper는 `/etc/config/oathkeeper/entrypoint.sh`를 통해 시작해야 합니다. entrypoint는 `APP_ENV`에 따라 env별 rules 파일을 고르고 `/tmp/oathkeeper/rules.active.json`을 생성합니다.
|
|
|
|
- `APP_ENV=stage|staging`: `rules.stage.json`
|
|
- `APP_ENV=production|prod`: `rules.prod.json`
|
|
- 그 외: `rules.json`
|
|
|
|
`docker/ory/oathkeeper/oathkeeper.yml`은 `file:///tmp/oathkeeper/rules.active.json`을 읽습니다. compose나 배포 템플릿이 entrypoint를 우회해 `oathkeeper serve proxy`를 직접 실행하면 active rules 생성이 누락될 수 있습니다.
|
|
|
|
## 7) 트러블슈팅
|
|
### 7.1 로그인 클릭 시 동작 없음
|
|
- 원인: Kratos 기동 실패(설정 파싱 실패 등) 또는 브라우저용 URL이 내부 도메인(`kratos:...`)으로 설정됨
|
|
- 확인:
|
|
- `docker logs ory_kratos`에서 config 오류 여부 확인
|
|
- 브라우저 네트워크 탭에서 `/self-service/login/browser` 응답 확인(302 Location 헤더)
|
|
|
|
### 7.2 kratos.yml에 ${...} 환경 변수 치환 실패
|
|
- Kratos 설정 파일은 `${ENV}` 치환을 지원하지 않음
|
|
- 해결: compose 환경 변수로 `KRATOS_SELFSERVICE_*`, `KRATOS_SERVE_*` 오버라이드 사용
|
|
|
|
## 8) 네트워크 접근 테스트
|
|
아래 스크립트는 **ory-net에서 Admin 포트 접근 가능** / **baron_net(Frontend 영역)에서 접근 불가**를 검증합니다.
|
|
|
|
```bash
|
|
bash test/ory-network-check.sh
|
|
```
|
|
|
|
직접 확인하려면:
|
|
```bash
|
|
# ory-net에서는 성공해야 함
|
|
docker run --rm --network ory-net curlimages/curl:8.10.1 -fsS http://hydra:4445/health/ready
|
|
docker run --rm --network ory-net curlimages/curl:8.10.1 -fsS http://kratos:4434/health/ready
|
|
|
|
# baron_net에서는 실패해야 함
|
|
docker run --rm --network baron_net curlimages/curl:8.10.1 -fsS http://hydra:4445/health/ready
|
|
docker run --rm --network baron_net curlimages/curl:8.10.1 -fsS http://kratos:4434/health/ready
|
|
```
|
|
|
|
## 9) 참고 파일
|
|
- `compose.ory.yaml`
|
|
- `docker/ory/kratos/kratos.yml`
|
|
- `.env.sample`
|
|
- `https://gitea.hmac.kr/baron/baron-sso/wiki/Authentication-and-Login-Flow.-`
|