kevin/baron-sso
1
0
Fork 0
forked from baron/baron-sso
Code Pull Requests Activity
Files
3e31fdfa0c7720d95d84cfecee6967a3cc63ee7d
baron-sso/docs/ory-usage.md

6.3 KiB
Raw Blame History

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) 실행 방법

# 인증 리다이렉트 설정 생성/검증
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 기반 실행을 사용할 경우:

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과 같아야 합니다.

예시(로컬):

KRATOS_BROWSER_URL=http://localhost:4433
KRATOS_UI_URL=http://localhost:5000

예시(리버스 프록시/도메인):

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 test/ory-network-check.sh

직접 확인하려면:

# 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.-
View Git Blame Copy Permalink