JWT로 API 접근 보호하기

원문 보기 위키 갱신 2026.10.03

출처: Secure API Access with JWT

본문

Secure API Access with JWT

Traefik Hub 기능

이 미들웨어는 Traefik Hub에서만 사용할 수 있어요. Traefik Hub의 고급 기능에 대해 자세히 알아보세요.

JSON Web Token(JWT, RFC 7519에 정의)은 Traefik Hub API Gateway가 비공개 서명 시크릿이나 공개/비공개 키로 서명된 토큰을 사용해 API 접근을 보호할 수 있게 해줘요.

Traefik Hub API Gateway는 토큰 검증을 수행할 여러 종류의 소스를 제공해요:

미들웨어 구성에 시크릿 값을 설정하기 (옵션 signingSecret).
공개 키 설정하기: 이 경우 사용자는 비공개 키로 토큰에 서명하고, 공개 키로 서명을 검증할 수 있어요 (옵션 publicKey).
들어오는 JWT의 서명을 검증하는 데 사용할 JWK 집합을 정의하는 JSON Web Key(JWK) 파일 설정하기 (옵션 jwksFile).
JWK 집합을 제공하는 호스트의 URL을 정의하는 JSON Web Key(JWK) URL 설정하기 (옵션 jwksUrl).

소스 하나만

JWT 미들웨어는 들어오는 토큰을 검증하는 방법을 하나보다 많이 설정하는 걸 허용하지 않아요. Hub API Gateway가 JWT 미들웨어로 검증해야 하는 요청을 받으면, 위에 설명한 대로 구성된 소스를 사용해 토큰을 검증해요. 토큰 검증이 성공하면 요청이 수락돼요.

클레임(Claim) 사용법

JWT는 클레임(키-값 쌍) 형태의 메타데이터를 담을 수 있어요. JWT에 포함된 클레임은 claims를 사용해 권한 부여(Authorization) 계층을 추가하는 것 같은 고급 사용 사례에 활용할 수 있어요.

자세한 내용은 전용 섹션에서 확인하세요.

시크릿으로 JWT 검증하기

Traefik Hub API Gateway가 Kubernetes 시크릿에 저장된 시크릿 값으로 JWT를 검증하게 하려면 다음 구성을 적용하세요:

Middleware JWT

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
  namespace: apps
spec:
  plugin:
    jwt:
      signingSecret: "urn:k8s:secret:jwt:signingSecret"

Kubernetes Secret

apiVersion: v1
kind: Secret
metadata:
  name: jwt
  namespace: apps
stringData:
  signingSecret: mysuperlongsecret

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
  - match: Path(`/my-app`)
    kind: Rule
    services:
    - name: whoami
      port: 80
    middlewares:
    - name: test-jwt

Service & Deployment

kind: Deployment
apiVersion: apps/v1
metadata:
  name: whoami
  namespace: apps
spec:
  replicas: 3
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
      - name: whoami
        image: traefik/whoami

---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: apps
spec:
  ports:
  - port: 80
    name: whoami
  selector:
    app: whoami

Identity Provider로 JWT 검증하기

Traefik Hub API Gateway가 아래 예시의 Keycloak, Azure AD 같은 Identity Provider로 JWT를 검증하게 하려면 다음 구성을 적용하세요:

JWKS with Keycloak URL

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
  namespace: apps
spec:
  plugin:
    jwt:
      # Replace KEYCLOAK_URL and REALM_NAME with your values
      jwksUrl: https://KEYCLOAK_URL/realms/REALM_NAME/protocol/openid-connect/certs
      # Forward the content of the claim grp in the header Group
      forwardHeaders:
        Group: grp
      # Check the value of the claim grp before sending the request to the backend
      claims: Equals(`grp`, `admin`)

JWKS with Azure AD URL

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
  namespace: apps
spec:
  plugin:
    jwt:
      jwksUrl: https://login.microsoftonline.com/common/discovery/v2.0/keys

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
  - match: Path(`/my-app`)
    kind: Rule
    services:
    - name: whoami
      port: 80
    middlewares:
    - name: test-jwt

Service & Deployment

kind: Deployment
apiVersion: apps/v1
metadata:
  name: whoami
  namespace: apps
spec:
  replicas: 3
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
      - name: whoami
        image: traefik/whoami

---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: apps
spec:
  ports:
  - port: 80
    name: whoami
  selector:
    app: whoami

고급 구성

고급 옵션은 reference 페이지에 설명되어 있어요.

예를 들어 Identity Provider에서 가져온 메타데이터로 애플리케이션 접근을 제한할 수 있어요. 그렇게 하려면 claims 옵션을 사용하면 되는데, 자세한 내용은 전용 섹션에서 확인하세요.

프로덕션에서 Traefik OSS를 사용 중인가요?

업무에서 Traefik을 사용한다면 엔터프라이즈급 API 게이트웨이 기능이나 Traefik OSS용 상용 지원을 고려해 보세요.

API Gateway 데모 영상 보기
24/7/365 OSS 지원 요청하기

Traefik OSS에 API 게이트웨이 기능을 추가하는 건 빠르고 매끄러워요. 대체(rip and replace)가 필요 없고 모든 구성이 그대로 유지돼요. 이 짧은 영상으로 직접 확인해 보세요.

더 알아보기

Traefik 공식 문서