JWT로 API 게이트웨이 요청 검증

JWT로 API 게이트웨이 요청 검증 (Kubernetes)

JSON Web Token(JWT)을 사용해 Kubernetes 오케스트레이션 컨테이너에 배포된 API 게이트웨이에 대한 요청을 검증하는 방법을 설명하는 문서예요.

출처: 문서

본문

이 주제는 JSON 웹 토큰(JWT)을 사용해 Kubernetes 오케스트레이션 컨테이너에 배포된 API 게이트웨이에 대한 요청을 검증하는 방법을 설명해요. API 게이트웨이가 가상 머신에 배포되었다면 VM에서 API 게이트웨이에 대한 요청 검증에 JWT 사용을 참고하세요.

참고 엔터프라이즈

이 기능은 Consul Enterprise에서 사용할 수 있어요.

개요 (Overview)

들어오는 요청을 검증하는 데 JWT를 사용하도록 API 게이트웨이를 구성해, 게이트웨이에서 검증되지 않은 트래픽을 중지할 수 있어요. JWT 검증을 서로 다른 수준에서 구성할 수 있어요:

  • 리스너 기본값: GatewayPolicy 리소스에 기본 기본값을 정의해 리스너에 연결된 모든 경로에 적용한다.
  • HTTP 경로별 설정: 특정 HTTP 경로에 대한 JWT 인증 설정을 정의할 수 있다. 경로별 JWT 설정은 기본 리스너 구성을 재정의한다.
  • 리스너 재정의: 기본 및 경로별 구성보다 우선하는 재정의 설정을 GatewayPolicy 리소스에 정의한다. 리스너에 대해 시행 가능한 정책을 설정하려면 재정의 설정을 사용한다.

요청 검증에 JWT를 사용하려면 다음 단계를 완료해요:

  1. 게이트웨이에 대한 요청을 검증하는 데 사용할 JWT 프로바이더와 클레임을 지정하는 JWTProvider를 정의한다.
  2. API 게이트웨이 리스너에 대한 기본 및 재정의 설정을 지정하고 게이트웨이에 연결하는 GatewayPolicy를 정의한다.
  3. 경로별 JWT 검증 설정을 지정하는 RouteAuthFilter를 정의한다.
  4. HTTPRoute에서 RouteAuthFilter를 참조한다.
  5. 구성을 적용한다.

요구 사항 (Requirements)

  • Consul v1.17+
  • Consul on Kubernetes CLI 또는 Helm 차트 v1.3.0+
  • 클레임과 프로바이더 같은 JWT 세부 정보

JWTProvider 정의 (Define a JWTProvider)

클레임을 검증할 JWT 프로바이더를 정의하는 JWTProvider CRD를 만들어요.

다음 예시에서 JWTProvider CRD는 로컬 JWKS를 포함해요. 프로덕션 환경에서는 프로덕션 등급의 JWKS 엔드포인트를 사용하세요.

jwt-provider.yaml

apiVersion: consul.hashicorp.com/v1alpha1
kind: JWTProvider
metadata:
  name: local
spec:
  issuer: local
  jsonWebKeySet:
    local:
      jwks: "<JWKS-Key>"

이 CRD에서 구성할 수 있는 필드에 대한 자세한 내용은 JWTProvider 구성 참조를 참고하세요.

GatewayPolicy 정의 (Define a GatewayPolicy)

JWT 검증에 대한 기본 및 재정의 설정을 정의하는 GatewayPolicy CRD를 만들어요.

  • kind: GatewayPolicy로 설정해야 해요.
  • metadata.name: 정책의 이름을 지정해요.
  • spec.targetRef.name: 정책을 연결할 API 게이트웨이의 이름을 지정해요.
  • spec.targetRef.kind: 정책을 연결할 리소스의 종류를 지정해요. Gateway로 설정해야 해요.
  • spec.targetRef.group: 리소스 그룹을 지정해요. 커스텀 그룹을 만들지 않았다면 gateway.networking.k8s.io/v1beta1로 설정해야 해요.
  • spec.targetRef.sectionName: 정책이 적용되는 게이트웨이의 일부를 지정해요.
  • spec.targetRef.override.jwt.providers: 게이트웨이에 대한 요청을 검증하는 데 사용할 프로바이더와 클레임 목록을 지정해요. 재정의 설정은 기본 및 경로별 JWT 검증 설정보다 우선해요.
  • spec.targetRef.default.jwt.providers: 게이트웨이에 대한 요청을 검증하는 데 사용할 기본 프로바이더와 클레임 목록을 지정해요.

다음 예시는 Gateway와 그것에 연결되는 GatewayPolicy를 구성해 리스너를 통해 들어오는 모든 요청이 다음 조건을 충족해야 하도록 해요:

  • 요청은 local 프로바이더가 서명해야 함
  • 리스너에 연결된 HTTPRoute가 재정의하지 않는 한 요청은 값이 user인 role 클레임을 가져야 함

Gateway — gateway.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: api-gateway
spec:
  gatewayClassName: consul
  listeners:
    - protocol: HTTP
      port: 30002
      name: listener-one

GatewayPolicy — gateway-policy.yaml

apiVersion: consul.hashicorp.com/v1alpha1
kind: GatewayPolicy
metadata:
  name: gw-policy
spec:
  targetRef:
    name: api-gateway
    sectionName: listener-one
    group: gateway.networking.k8s.io/v1
    kind: Gateway
  override:
    jwt:
      providers:
      - name: "local"
  default:
    jwt:
      providers:
      - name: "local"
        verifyClaims:
        - path:
            - role
          value: user

구성할 수 있는 필드에 대한 자세한 내용은 GatewayPolicy 구성 참조를 참고하세요.

RouteAuthFilter 정의 (Define a RouteAuthFilter)

GatewayPolicy에 구성된 기본 JWT 검증에 대한 재정의를 정의하는 RouteAuthFilter CRD를 만들어요.

  • kind: RouteAuthFilter로 설정해야 해요.
  • metadata.name: 필터의 이름을 지정해요.
  • metadata.namespace: 필터가 적용되는 Consul 네임스페이스를 지정해요.
  • spec.jwt.providers: 게이트웨이에 대한 요청을 검증하는 데 사용할 프로바이더와 클레임 목록을 지정해요. 재정의 설정은 기본 및 경로별 JWT 검증 설정보다 우선해요.

다음 예시에서 RouteAuthFilter는 GatewayPolicy에 설정된 기본 설정을 재정의해 리스너를 통해 들어오는 모든 요청이 다음 조건을 충족하도록 해요:

  • 요청은 local 프로바이더가 서명해야 함
  • 요청은 role 클레임을 가져야 함
  • 클레임의 값은 admin이어야 함

route-auth-filter.yaml

apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteAuthFilter
metadata:
  name: auth-filter
spec:
  jwt:
    providers:
    - name: local
      verifyClaims:
      - path:
          - role
        value: admin

구성할 수 있는 필드에 대한 자세한 내용은 RouteAuthFilter 구성 참조를 참고하세요.

HTTP 경로에 인증 필터 연결 (Attach the auth filter to your HTTP routes)

HTTPRoute 구성의 filters 필드에서 JWT 검증 결과로 발생하는 필터 동작을 정의해요.

  • type: extensionRef: 확장 참조 목록을 선언해요.
  • extensionRef.group: 리소스 그룹을 지정해요. 커스텀 그룹을 만들지 않았다면 gateway.networking.k8s.io/v1로 설정해야 해요.
  • extensionRef.kind: 경로에 연결할 확장 참조의 유형을 지정해요. RouteAuthFilter여야 해요.
  • extensionRef.name: 인증 필터의 이름을 지정해요.

다음 예시는 api-gateway-fqdn:3002/admin에 대한 모든 요청이 다음 조건을 충족해야 하도록 HTTPRoute를 구성해요:

  • 요청이 local 프로바이더가 서명해야 함.
  • 요청이 role 클레임을 가져야 함.
  • 클레임의 값이 admin이어야 함.

다른 모든 요청은 GatewayPolicy에 정의된 대로 local 프로바이더가 서명하고 값이 user인 role 클레임을 가져야 해요.

http-route.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-route
spec:
  parentRefs:
    - name: api-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /admin
      filters:
        - type: ExtensionRef
          extensionRef:
            group: consul.hashicorp.com
            kind: RouteAuthFilter
            name: auth-filter
      backendRefs:
        - kind: Service
          name: admin
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - kind: Service
          name: user-service
          port: 8081

더 알아보기 (Learn more)