인증

GenD 플랫폼의 인증 아키텍처를 안내합니다. Keycloak SSO + JWT 토큰 기반 인증을 사용합니다.

개요

GenD는 Keycloak을 IdP(Identity Provider)로 사용하여 OpenID Connect 프로토콜 기반의 SSO 인증을 제공합니다. UI는 PKCE 플로우로 토큰을 발급받고, API는 JWT Bearer 토큰을 검증합니다.

인증 흐름

OIDC 신뢰 체인

GenD 의 12개+ 서비스가 모두 Keycloak realm gend 를 IdP로 사용하지만, 인증 패턴은 3종으로 나뉩니다 — 직접 JWT, ForwardAuth (oauth2-proxy), Native OIDC. Keycloak client secret은 SealedSecret 단일 원본으로 관리됩니다(secret 다층 동기화 사고 방지 #580).

클라이언트 매트릭스

클라이언트	타입	인증 흐름	용도
`gend-ui`	public	PKCE S256	React UI
`gend-api`	confidential	bearer-only	REST API audience
`trino`	confidential	client_credentials	Trino JWT (coordinator-only)
`oauth2-proxy`	confidential	authorization_code	ForwardAuth 중개
`jupyterhub`	confidential	client_credentials	JupyterHub OIDC
`grafana`	confidential	authorization_code	Grafana native OIDC

Secret 동기화 안전장치

Keycloak client secret이 4곳에 동시 존재할 수 있어(SealedSecret · realm-export · ConfigMap · K8s Secret), 동기화 잡이 secret을 잘못 덮어쓰는 사고가 반복됐습니다 (#572~#581). 현재는:

SealedSecret을 단일 원본으로 고정
realm-sync Job 의 kcadm update PUT body 에서 secret 필드 strip
강제 set 단계 추가 ([2.5/4])
KCTX 가드 (다른 realm 오작용 차단)

주요 구성 요소

구성 요소	설명
Keycloak	IdP 서버, `gend` Realm 관리
gend-ui 클라이언트	Public Client, PKCE S256
gend-api 클라이언트	Confidential, 토큰 audience 검증
JWT Bearer	RS256 알고리즘, JWKS 엔드포인트 자동 갱신

인증 관련 설정

환경 변수	기본값	설명
`GEND_AUTH_ENABLED`	`true`	인증 기능 활성화
`GEND_KEYCLOAK_URL`	`http://keycloak:8080/auth`	Keycloak 내부 URL
`GEND_KEYCLOAK_REALM`	`gend`	Realm 이름
`GEND_KEYCLOAK_CLIENT_ID`	`gend-api`	API 클라이언트 ID

인증 불필요 엔드포인트

다음 엔드포인트는 JWT 토큰 없이 접근 가능합니다:

/health — 헬스체크
/metrics — Prometheus 메트릭
/api/v1/abuse/webhook — HMAC-SHA256 웹훅 (JWT 대신 HMAC 인증)

개요​

인증 흐름​

OIDC 신뢰 체인​

클라이언트 매트릭스​

Secret 동기화 안전장치​

주요 구성 요소​

인증 관련 설정​

인증 불필요 엔드포인트​

관련 문서​

개요