본문으로 건너뛰기

JWT 토큰

GenD API의 JWT 토큰 검증 메커니즘과 구성 방법입니다.

개요​

GenD API는 Keycloak에서 발급한 RS256 JWT 토큰을 JWKS(JSON Web Key Set) 엔드포인트를 통해 검증합니다. apps/api/src/gend_api/auth/jwt_bearer.py에서 PyJWT 라이브러리를 사용합니다.

토큰 검증 과정​

  1. Authorization: Bearer <token> 헤더에서 JWT 추출
  2. JWKS 엔드포인트(/realms/gend/protocol/openid-connect/certs)에서 서명 키 획득
  3. RS256 알고리즘으로 서명 검증
  4. issuer, audience, 만료 시간 검증
  5. TokenPayload 객체로 디코딩

검증 설정​

검증 항목설정
알고리즘RS256
issuer{keycloak_url}/realms/gend
audiencegend-api (GEND_KEYCLOAK_CLIENT_ID)
만료 검증활성화
JWKS 캐시60초

Issuer URL 설정​

내부/외부 URL이 다른 환경에서는 GEND_KEYCLOAK_ISSUER_URL을 설정합니다.

# 내부 URL (Pod 간 통신)
GEND_KEYCLOAK_URL=http://keycloak:8080/auth

# 외부 URL (토큰 issuer 검증용)
GEND_KEYCLOAK_ISSUER_URL=https://gend.local:8443/auth

GEND_KEYCLOAK_ISSUER_URL이 비어 있으면 GEND_KEYCLOAK_URL을 issuer 기준으로 사용합니다. 외부 URL에는 /realms/{realm}을 포함하지 마세요.

토큰 발급 테스트​

# Password Grant (테스트/개발 전용)
curl -s -X POST \
  "http://localhost:31800/auth/realms/gend/protocol/openid-connect/token" \
  -d "grant_type=password&client_id=gend-ui&username=admin&password=admin" \
  | jq '.access_token'

에러 코드​

HTTP 상태원인
401 Missing authentication tokenAuthorization 헤더 없음
401 Token has expired토큰 만료 (기본 30분)
401 Invalid authentication token서명/issuer/audience 불일치

선택적 인증​

get_optional_user 의존성을 사용하면 토큰 없이도 접근 가능한 엔드포인트를 구현할 수 있습니다. 토큰이 있으면 사용자 정보를 반환하고, 없으면 None을 반환합니다.

관련 문서​