신원 강제(Identity Enforcement)
이용 대상
이 문서는 플랫폼 관리자를 대상으로 합니다. 서빙 게이트웨이가 요청의 신원
(X-GenOS-Identity JWT)을 검증하고, 역할별로 사용 가능한 모델을 게이팅하며,
감사 로그를 남기는 기능을 배포별로 켜고 끄는 방법을 다룹니다.
기본값은 permissive
신원 강제는 기본적으로 꺼져 있습니다(permissive). 이 상태에서는 게이트웨이가
X-GenOS-Identity 헤더 유무와 무관하게 기존 서빙 키(sk-svp-*) 흐름을 그대로
처리합니다. 배포별로 강제를 켜려면 게이트웨이 env GENOS_SSO_ENFORCE=1 을
설정합니다.
강제(enforce)는 fail-closed 로 동작합니다 — 신원이 없거나 무효하면 요청이 거부됩니다. 따라서 켜기 전에 아래 체크리스트를 반드시 확인하세요.
켜기 전 체크리스트
하나라도 빠지면 정상 사용자까지 차단될 수 있습니다.
- IdP(Keycloak) 매퍼 — realm roles 매퍼를 "Add to ID token" ON 으로 설정하고, group membership 매퍼를 추가합니다. 미설정 시 전 사용자가 403 으로 거부됩니다.
GENOS_SSO_AUDIENCE설정 — 없으면 게이트웨이가 코드 레벨에서 전량 401 로 거절합니다(의도된 fail-closed).- 운영 프로브용 신원 준비 — 헬스체크·스모크 테스트 등 운영 도구도
X-GenOS-Identity없이는 강제 배포에서 401 을 받습니다. 서비스 계정 토큰 발급 등 대응 방안을 미리 마련하세요. - 정책 파일 변경 시 게이트웨이 재기동 — role→모델 정책은 프로세스에 캐시되므로, 파일만 바꾸고 재기동하지 않으면 이전 정책이 계속 적용됩니다.
env 표
| 변수 | 설명 |
|---|---|
GENOS_SSO_ENFORCE | 1 로 설정하면 강제(enforce) 모드. 그 외 값·미설정 = permissive |
GENOS_SSO_ISSUER | IdP issuer URL. 소문자 URL 권장 — 브라우저가 host 를 소문자화하므로 대소문자가 불일치하면 Invalid issuer 오류가 발생합니다 |
GENOS_SSO_AUDIENCE | 클라이언트 ID. 필수(미설정 시 전량 401) |
GENOS_SSO_JWKS_URL | 생략 시 GENOS_SSO_ISSUER 에서 파생됩니다 |
GENOS_SSO_ROLE_MODEL_POLICY | role→모델 정책 파일 경로. 스키마는 정책 파일 참고 |
GENOS_AUDIT_HMAC_KEY | 감사 체인 HMAC 키. 미설정 시 감사 체인 비활성 |
원문
체크리스트 각 항목의 상세 절차·롤백·알려진 범위 한계는 게이트웨이 레포의
docs/identity-enforcement-runbook.md 문서가 진실의 원천입니다. 실제 활성화
작업 전에는 반드시 그 문서의 전체 절차를 따르세요.