API Gateway에서의 OIDC 토큰 검증 — Istio, Envoy, Gateway API 실전

            [엣지: 1차 검증 - 서명/iss/exp/aud]
  Client ──> API Gateway (Envoy jwt_authn) ──┐
                                             │ mTLS (서비스 신원)
                                             v
                              [서비스: 2차 검증 + 세밀한 인가]
                              Service A (sidecar RequestAuthentication)
                                             │ 토큰 전파 or exchange
                                             v
                              Service B (sidecar + AuthorizationPolicy)

http_filters:
  - name: envoy.filters.http.jwt_authn
    typed_config:
      '@type': type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication
      providers:
        keycloak_provider:
          issuer: https://keycloak.example.com/realms/prod
          audiences:
            - orders-api
          remote_jwks:
            http_uri:
              uri: https://keycloak.example.com/realms/prod/protocol/openid-connect/certs
              cluster: keycloak_jwks_cluster
              timeout: 3s
            cache_duration: 600s
            async_fetch:
              fast_listener: false
            retry_policy:
              num_retries: 3
          # Authorization: Bearer 헤더에서 추출 (기본값)
          from_headers:
            - name: Authorization
              value_prefix: 'Bearer '
          # 검증된 페이로드를 메타데이터로 저장해 후속 필터(RBAC 등)가 활용
          payload_in_metadata: jwt_payload
          # 검증 후 업스트림에 평문 클레임 헤더로 전달
          claim_to_headers:
            - header_name: x-jwt-sub
              claim_name: sub
            - header_name: x-jwt-scope
              claim_name: scope
          # 업스트림으로 원본 토큰을 제거할지 유지할지
          forward: true
          # exp 검증의 클럭 스큐 허용
          clock_skew_seconds: 30
      rules:
        # 헬스체크는 토큰 불요
        - match:
            prefix: /healthz
        # 공개 문서 엔드포인트는 토큰이 있으면 검증, 없어도 통과
        - match:
            prefix: /docs
          requires:
            requires_any:
              requirements:
                - provider_name: keycloak_provider
                - allow_missing: {}
        # 나머지는 모두 필수
        - match:
            prefix: /
          requires:
            provider_name: keycloak_provider

apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: ingress-jwt
  namespace: istio-system
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  jwtRules:
    - issuer: https://keycloak.example.com/realms/prod
      jwksUri: https://keycloak.example.com/realms/prod/protocol/openid-connect/certs
      audiences:
        - api-gateway
      forwardOriginalToken: true
      outputClaimToHeaders:
        - header: x-jwt-sub
          claim: sub
---
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: ingress-require-jwt
  namespace: istio-system
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  action: DENY
  rules:
    - from:
        - source:
            notRequestPrincipals: ['*']
      to:
        - operation:
            notPaths: ['/healthz', '/metrics']

apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: orders-jwt
  namespace: orders
spec:
  selector:
    matchLabels:
      app: orders
  jwtRules:
    - issuer: https://keycloak.example.com/realms/prod
      jwksUri: https://keycloak.example.com/realms/prod/protocol/openid-connect/certs
      audiences:
        - orders-api
---
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: orders-authz
  namespace: orders
spec:
  selector:
    matchLabels:
      app: orders
  action: ALLOW
  rules:
    # 읽기: 인증된 주체면 허용
    - from:
        - source:
            requestPrincipals: ['https://keycloak.example.com/realms/prod/*']
      to:
        - operation:
            methods: ['GET']
            paths: ['/orders', '/orders/*']
    # 쓰기: orders:write 스코프 요구
    - from:
        - source:
            requestPrincipals: ['https://keycloak.example.com/realms/prod/*']
      to:
        - operation:
            methods: ['POST', 'PUT', 'DELETE']
            paths: ['/orders', '/orders/*']
      when:
        - key: request.auth.claims[scope]
          values: ['*orders:write*']

Client --(JWT aud=api)--> Gateway --(같은 JWT)--> Service A --(같은 JWT)--> Service B

curl -s -X POST https://keycloak.example.com/realms/prod/protocol/openid-connect/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d client_id=service-a \
  -d client_secret=SERVICE_A_SECRET \
  -d subject_token=ORIGINAL_USER_ACCESS_TOKEN \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d audience=service-b

{
  "iss": "https://keycloak.example.com/realms/prod",
  "sub": "user-1234",
  "aud": "service-b",
  "scope": "orders:read",
  "act": {
    "sub": "service-account-service-a"
  },
  "exp": 1781234567
}

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  name: orders-route
  namespace: apps
spec:
  http:
    - name: orders
      match:
        hosts:
          - api.example.com
        paths:
          - /orders/*
      backends:
        - serviceName: orders
          servicePort: 8080
      plugins:
        - name: openid-connect
          enable: true
          config:
            discovery: https://keycloak.example.com/realms/prod/.well-known/openid-configuration
            client_id: apisix-gateway
            client_secret: GATEWAY_CLIENT_SECRET
            bearer_only: true
            use_jwks: true
            token_signing_alg_values_expected: RS256
            audience: orders-api

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: orders-jwt
  namespace: apps
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: orders-route
  jwt:
    providers:
      - name: keycloak
        issuer: https://keycloak.example.com/realms/prod
        audiences:
          - orders-api
        remoteJWKS:
          uri: https://keycloak.example.com/realms/prod/protocol/openid-connect/certs
        claimToHeaders:
          - claim: sub
            header: x-jwt-sub

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: orders
spec:
  mtls:
    mode: STRICT
---
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: orders-payment-call
  namespace: payments
spec:
  selector:
    matchLabels:
      app: payments
  action: ALLOW
  rules:
    - from:
        - source:
            # 호출자 워크로드 제한 (mTLS 기반 서비스 신원)
            principals: ['cluster.local/ns/orders/sa/orders-sa']
            # 최종 사용자 토큰도 함께 요구
            requestPrincipals: ['https://keycloak.example.com/realms/prod/*']
      to:
        - operation:
            methods: ['POST']
            paths: ['/payments']
      when:
        - key: request.auth.claims[scope]
          values: ['*payments:write*']

                         +--------------------------+
                         | 401 발생                  |
                         +-----------+--------------+
                                     |
                  토큰이 요청에 실려 있는가? (헤더 확인)
                                     |
              +----------- 아니오 ---+--- 예 -----------+
              |                                         |
   클라이언트/프록시가 Authorization          jwt.io 등으로 토큰 디코드(검증 말고 관찰)
   헤더를 누락/제거? (프록시 체인 점검)                  |
                                     +------------------+------------------+
                                     |                  |                  |
                               iss가 설정과         exp가 지났는가?    aud가 설정과
                               정확히 일치?         (클럭 스큐 포함)   일치하는가?
                                     |                  |                  |
                              불일치: trailing      만료: 갱신 로직    불일치: audience
                              slash, http/https,    점검, NTP 확인     매핑 재설계
                              realm 경로 확인
                                     |
                         모두 정상이면 → 키 검증 단계 의심
                                     |
                  +------------------+-------------------+
                  |                                      |
        토큰 헤더의 kid가 JWKS에                게이트웨이가 JWKS를
        존재하는가? (curl로 JWKS 확인)          가져올 수 있는가?
                  |                                      |
        없음: 키 롤테이션 직후 캐시          fetch 실패: 클러스터 정의,
        문제 → 캐시 TTL/롤테이션 유예        DNS, egress 정책, TLS 신뢰
        정책 점검                            체인 점검
                  |
        모두 정상인데 401 → RequestAuthentication은 통과하고
        AuthorizationPolicy에서 거부(403일 수도)인지,
        룰 매칭(경로/메서드/스코프)을 점검

# 1) 토큰 페이로드 확인 (서명 검증 없이 디코드)
TOKEN=eyJhbGciOi...
echo "$TOKEN" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null | jq .

# 2) JWKS 직접 조회 — kid 목록 확인
curl -s https://keycloak.example.com/realms/prod/protocol/openid-connect/certs | jq '.keys[].kid'

# 3) Istio 설정이 Envoy에 반영됐는지 확인
istioctl proxy-config listener deploy/istio-ingressgateway -n istio-system -o json \
  | jq '.. | select(.name? == "envoy.filters.http.jwt_authn")'

# 4) Envoy 액세스 로그에서 거부 사유 플래그 확인
kubectl logs deploy/istio-ingressgateway -n istio-system | grep -E '401|403' | tail -5

# 5) jwt_authn 통계로 어느 단계에서 막히는지 확인
kubectl exec deploy/istio-ingressgateway -n istio-system -- \
  pilot-agent request GET stats | grep -E 'jwt_authn|jwks'