F5 AI Gateway JWT 인증 및 클레임 기반 라우팅 구성 가이드

F5 AI Gateway 는 JWT(JSON Web Token)를 통해 인증을 진행하고, 클레임값에 따라 지정한 서비스(모델)로 요청을 라우팅하도록 구성할 수 있습니다. 이를 통해, 토큰 내 정보를 기반으로 백엔드 LLM을 선택적으로 사용할 수 있어 보안성과 효율성을 모두 갖춘 AI 서비스 운영이 가능합니다.

다만 F5는 클라이언트 인증을 F5 AI Gateway가 아닌 앞단의 HTTP 리버스 프록시에서 처리하는 것을 권장하며, NGINX Plus Ingress Controller에서 JWT를 통해 인증하고 F5 AI Gateway에서 인증을 진행한 JWT의 클레임값에 따른 라우팅 구성도 가능합니다.

이 가이드는 Ollama를 백엔드 LLM 서비스로 사용하고, NGINX Plus Ingress Controller를 거쳐서 F5 AI Gateway로 요청이 전달되는 구조를 기반으로 합니다.

목차

1. 환경 및 버전 정보
2. F5 AI Gateway JWT 클레임 기반 라우팅 이해
3. JWT 설정 및 서명키 준비
4. F5 AI Gateway JWT 클레임 기반 라우팅 설정 및 동작 확인
5. NGINX Plus Ingress Controller 연동 F5 AI Gateway JWT 인증 및 라우팅
 5-1. NGINX Plus Ingress Controller JWT 인증 구성
 5-2. F5 AI Gateway 라우팅 동작 확인
6. 결론

1. 환경 및 버전 정보

  • Kubernetes: v1.32.2
  • NGINX Plus Ingress Controller: 5.0.0
  • F5 AI Gateway: v1.0.2
  • F5 AI Gateway Helm chart: aigw-0.1.1
  • Ollama: 0.6.5

2. F5 AI Gateway JWT 클레임 기반 라우팅 이해

F5 AI Gateway는 policies 섹션에 authentication 설정을 통해 JWT 인증을 구성하고, selector를 사용하여 JWT 토큰 내 클레임값에 따라 서로 다른 profile로 요청을 라우팅할 수 있습니다. 다만 JWT의 클레임 중 aud, sub 2개의 클레임을 사용할 수 있습니다.

예시 구성은 아래와 같습니다.

policies:
  - name: chat-policy
    authentication:
      jwtSigningKeyFile: /app/.certs/jwtHS256.key
      jwtSigningKeyType: HS256
    profiles:
      - name: premium-profile
        selector:
          type: jwt
          key: sub
          values:
            - premium
      - name: standard-profile
        selector:
          type: jwt
          key: sub
          values:
            - normal

profiles:
  - name: premium-profile
    services:
      - name: ollama/hermes
  - name: standard-profile
    services:
      - name: ollama/tinyllama

services:
  - name: ollama/hermes
    type: hermes3:8b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"
  - name: ollama/tinyllama
    type: tinyllama:1.1b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"
  • authentication: JWT 인증 설정을 지정합니다.
    • jwtSigningKeyFile: JWT 서명 검증을 위한 키 파일 경로입니다.
    • jwtSigningKeyType: JWT 서명 알고리즘 유형을 지정합니다.
  • selector: JWT 클레임값을 사용해 profile을 매칭하기 위해 구성합니다.
    • type: JWT 클레임 기반 매칭을 사용하기 위해 jwt로 설정합니다.
    • key: JWT 토큰 내에서 확인할 클레임의 키를 지정합니다. aud, sub 값을 지정할 수 있습니다.
    • values: 매칭할 클레임의 값을 지정합니다.

policies, profile, service에 대한 상세 설명은 F5 AI Gateway 설정 기초 가이드 포스트를 참고하세요.

3. JWT 설정 및 서명키 준비

1. JWT의 토큰 암호화에 사용할 알고리즘을 선택합니다.

F5 AI Gateway는 다음과 같은 암호화 알고리즘을 지원합니다.

  • HS256
  • HS384
  • HS512
  • ES256
  • ES384
  • ES512
  • RS256
  • RS384
  • RS512
  • EdDSA

이 포스트에서는 HS256 알고리즘을 사용하여 진행했습니다.

2. JWT를 서명하기 위한 무작위 비밀 키를 생성합니다.

HS256 알고리즘의 경우 256비트(32바이트) 이상의 키를 요구하여 다음 명령어를 사용해 생성했습니다.

$ openssl rand -base64 32

아래와 같은 무작위 문자열이 생성됩니다.

Tmdg0KV5jpS4Z4PvVS5CfUQlToJFCUPIrc6upuxV+Hs=

3. 생성한 문자열을 사용하여 Kubernetes secret을 생성합니다.

aigw-jwt 이름으로 생성했으며, jwtHS256.key라는 키의 값으로 앞서 생성한 문자열을 지정합니다. jwtHS256.key는 AI Gateway Pod 내부에 마운트되어 JWT 인증 설정에서 참조됩니다.

$ kubectl create secret generic aigw-jwt -n ai-gateway --from-literal jwtHS256.key=Tmdg0KV5jpS4Z4PvVS5CfUQlToJFCUPIrc6upuxV+Hs=

4. 생성한 JWT 서명 키 secret을 Pod 내부로 마운트하기 위해 F5 AI Gateway의 Helm value를 수정합니다.

......

aigw:

......

  volumeMounts:
    - name: jwt-volume
      readOnly: true
      mountPath: "/app/.certs"

  volumes:
    - name: jwt-volume
      secret:
        secretName: aigw-jwt

앞서 생성한 JWT 서명 키 secret이 Pod 내부로 마운트 되어 /app/.certs/jwtHS256.key 파일로 마운트됩니다.

4. F5 AI Gateway JWT 클레임 기반 라우팅 설정 및 동작 확인

F5 AI Gateway에 JWT 클레임 기반 라우팅 설정을 적용하고, Postman으로 요청을 전송하여 응답을 확인하겠습니다.

F5 AI Gateway 설정의 policies에서 JWT 인증 설정 및 라우팅 설정을 구성합니다.
전체 구성은 다음과 같습니다.

version: 1

server:
  address: :4141

logging:
  level: debug

routes:
  - path: /v1/chat/completions
    policy: chat-policy
    schema: v1/chat_completions  
    timeoutSeconds: 240
  - path: /v1/models
    policy: chat-policy
    schema: v1/models

policies:
  - name: chat-policy
    authentication:
      jwtSigningKeyFile: /app/.certs/jwtHS256.key
      jwtSigningKeyType: HS256
      
    profiles:
      - name: hermes-profile
        selector:
          type: jwt
          key: sub
          values:
            - premium
      - name: tinyllama-profile
        selector:
          type: jwt
          key: sub
          values:
            - normal

profiles:
  - name: hermes-profile
    services:
      - name: ollama/hermes
  - name: tinyllama-profile
    services:
      - name: ollama/tinyllama

services:
  - name: ollama/hermes
    type: hermes3:8b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"
  - name: ollama/tinyllama
    type: tinyllama:1.1b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"

앞서 구성한 JWT 서명 키를 사용해 JWT 인증을 진행하고, JWT의 sub 클레임값에 따라 서로 다른 모델로 요청을 라우팅합니다. sub 클레임의 값이 premium일 경우 hermes 모델, normal일 경우 tinyllama 모델이 요청을 처리합니다.

jwt.io에서 JWT를 생성합니다.

F5 AI Gateway 인증용 JWT 생성 - sub: premium
F5 AI Gateway 인증용 JWT 생성 - sub: premium

앞서 선택한 알고리즘, 라우팅 확인을 위한 sub 클레임, JWT 서명 키값을 사용해 JWT를 생성합니다.

F5 AI Gateway JWT 요청 전송

생성한 JWT를 Authorization 헤더의 값에 담아 Postman으로 요청을 전송합니다. F5 AI Gateway는 Authorization 헤더의 값의 bearer 값 존재 여부와 무관하게 JWT 인증을 진행합니다.

F5 AI Gateway JWT 요청 전송 결과 - hermes

sub 클레임의 값이 premium인 JWT를 사용해 요청을 전송하여 hermes 모델이 요청을 처리하고 응답합니다.

F5 AI Gateway 인증용 JWT 생성 - sub: normal
F5 AI Gateway 인증용 JWT 생성 - sub: normal

sub 클레임의 값을 normal로 변경하여 새로운 JWT를 생성합니다.

F5 AI Gateway JWT 요청 전송

새로 생성한 JWT를 Authorization 헤더에 담아 요청을 전송합니다.

F5 AI Gateway JWT 요청 전송 결과 - tinyllama

sub 클레임의 값이 normal인 JWT를 사용해 요청을 전송하여 tinyllama 모델이 요청을 처리하고 응답합니다.

5. NGINX Plus Ingress Controller 연동 F5 AI Gateway JWT 인증 및 라우팅

F5 AI Gateway에서 JWT 인증을 처리하지 않고, 앞단의 NGINX Plus Ingress Controller에서 JWT 인증을 처리하고, 전달받은 클레임 정보를 기반으로 라우팅하도록 구성하겠습니다.

NGINX Ingress Controller의 JWT 인증 기능은 NGINX Plus Ingress Controller 전용 기능입니다.
NGINX Plus Ingress Controller의 JWT 인증 구성에 대한 더 자세한 내용은 Kubernetes Secret 활용 NGINX Ingress Controller JWT 인증 설정 포스트를 참고하세요.

5-1. NGINX Plus Ingress Controller JWT 인증 구성

NGINX Plus Ingress Controller의 JWT 인증은 jwk 파일을 사용하기 때문에, jwk 파일 형식에 맞춰 secret을 생성해야 합니다. 이전의 예시에서 사용한 서명키를 사용하겠습니다.

Tmdg0KV5jpS4Z4PvVS5CfUQlToJFCUPIrc6upuxV+Hs=

1. 서명 키를 base64 형식으로 인코딩합니다.

$ echo -n Tmdg0KV5jpS4Z4PvVS5CfUQlToJFCUPIrc6upuxV+Hs= | base64

VG1kZzBLVjVqcFM0WjRQdlZTNUNmVVFsVG9KRkNVUElyYzZ1cHV4VitIcz0=

2. 인코딩한 값을 사용하여 jwk 파일을 생성합니다. 파일의 이름은 jwk로 생성합니다.

{"keys":
    [{
        "k":"VG1kZzBLVjVqcFM0WjRQdlZTNUNmVVFsVG9KRkNVUElyYzZ1cHV4VitIcz0=",
        "kty":"oct"
    }]
}

3. 생성한 jwk 파일을 사용하여 nginx.org/jwk 타입의 secret을 생성합니다. 

$ kubectl create secret generic nic-aigw-jwt --type=nginx.org/jwk -n ai-gateway --from-file=jwk

4. 생성된 secret을 확인합니다. 데이터의 키 이름은 secret 생성에 사용한 파일의 이름인 jwk로 구성됩니다.
데이터의 키 이름이 jwk가 아닐 경우 인증이 정상적으로 처리되지 않으므로 주의가 필요합니다.

$ kubectl describe secrets nic-aigw-jwt -n ai-gateway 

Name:         nic-aigw-jwt
Namespace:    ai-gateway
Labels:       <none>
Annotations:  <none>

Type:  nginx.org/jwk

Data
====
jwk:  124 bytes

5. NGINX Plus Ingress Controller의 JWT 인증을 위한 policy를 생성합니다.

apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: aigw-jwt
  namespace: ai-gateway
spec:
  jwt:
    secret: nic-aigw-jwt # 앞서 생성한 jwk secret 이름 지정 
    realm: "AI Gateway"

기본적으로 Authorization 헤더를 통해 전달받은 JWT로 인증을 진행하며, 전달받을 헤더를 변경하거나, Cookie 또는 쿼리 문자열의 일부로 전달받도록 설정할 수 있습니다.

이 포스트에서는 jwk 파일을 Kubernetes secret으로 생성하여 JWT 인증을 진행했지만, URL을 통해 JWKS를 가져와 사용하는 구성도 가능합니다. 정책 리소스 문서를 참고하세요.

6. 앞서 생성한 aigw-jwt policy를 적용하기 위해 VirtualServer 설정을 수정합니다.

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: aigw-jwt
  namespace: ai-gateway
spec:
  host: aigw.example.com
  upstreams:
    - name: aigw
      service: aigw
      port: 80
      connect-timeout: 240s
      read-timeout: 240s
      send-timeout: 240s
      client-max-body-size: 512k
    
  routes:
    - path: /
      policies:
        - name: aigw-jwt  # 생성한 policy 이름 지정
      action:
        proxy:
          upstream: aigw
          requestHeaders:
            set:
              - name: nic-sub           # JWT의 sub 클레임값을 Nic-Sub 헤더에 담아 백엔드(AI GW)로 전달
                value: ${jwt_claim_sub}
              - name: nic-role          # JWT의 커스텀 클레임도 사용 가능
                value: ${jwt_claim_role}
              - name: authorization     # JWT를 전달받은 헤더의 값을 빈값으로 변경하여 백엔드에는 JWT를 전달하지 않음
                value: ""

aigw-jwt policy를 통해서 JWT 인증을 진행하며, 해당 JWT의 클레임값을 헤더로 F5 AI Gateway로 전달합니다. 그리고 Authorization 헤더의 값을 빈 값으로 변경하여 JWT 토큰은 F5 AI Gateway로 전달하지 않습니다.

기존 F5 AI Gateway에서 JWT 인증 구성 시 클레임을 통한 라우팅은 aud, sub 2개의 클레임으로 제한되었으나, NGINX Plus Ingress Controller를 통해 JWT 인증을 진행할 때 커스텀 클레임을 포함하여 제한 없이 헤더로 전달하여 라우팅할 수 있습니다.

7. AI Gateway의 설정을 변경합니다.

version: 1

server:
  address: :4141

logging:
  level: debug

routes:
  - path: /v1/chat/completions
    policy: chat-policy
    schema: v1/chat_completions  
    timeoutSeconds: 240
  - path: /v1/models
    policy: chat-policy
    schema: v1/models

policies:
  - name: chat-policy
      
    profiles:
      - name: hermes-profile
        selector:
          type: header
          key: nic-role
          values:
            - admin
      - name: tinyllama-profile
        selector:
          type: header
          key: nic-role
          values:
            - user

profiles:
  - name: hermes-profile
    services:
      - name: ollama/hermes
  - name: tinyllama-profile
    services:
      - name: ollama/tinyllama

services:
  - name: ollama/hermes
    type: hermes3:8b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"
  - name: ollama/tinyllama
    type: tinyllama:1.1b
    executor: ollama
    config:
      endpoint: "http://192.168.200.129:11434/api/chat"

NGINX Plus Ingress Controller가 JWT의 클레임값을 추출하여 헤더로 F5 AI Gateway로 전달하기 때문에, F5 AI Gateway의 헤더 기반 라우팅 구성을 사용합니다. nic-role 헤더(role 클레임) 값이 admin일 경우 hermes, user일 경우 tinyllama 모델이 요청을 처리합니다.

5-2. F5 AI Gateway 라우팅 동작 확인

role 클레임의 값이 admin인 JWT를 생성합니다.

생성한 JWT를 Authorization 헤더에 담아서 요청을 전송합니다. 이전 예제와 달리 NGINX Plus Ingress Controller의 JWT 인증은 Bearer 타입을 명시해야 합니다. Bearer 타입이 생략된 경우 401 응답을 반환합니다.

role 클레임값이 admin으로 구성되어 hermes 모델이 요청을 처리하고 응답합니다.

role 클레임의 값이 user인 JWT를 생성합니다.

생성한 JWT를 Authorization 헤더에 담아서 요청을 전송합니다.

tinyllama 모델이 요청을 처리하고 응답하는 것을 확인할 수 있습니다.

6. 결론

이번 가이드를 통해 F5 AI Gateway와 NGINX Plus Ingress Controller를 활용한 JWT 인증 및 클레임 기반 라우팅 구성을 살펴보았습니다. 특히, NGINX Plus Ingress Controller에서 JWT 인증을 처리하고, 클레임 정보를 기반으로 요청을 라우팅하는 방식은 보안성과 확장성을 동시에 확보할 수 있는 효과적인 방법입니다.

이러한 구성을 통해 인증과 라우팅을 분리하여 관리함으로써 시스템의 유연성과 유지보수성을 향상할 수 있습니다. 또한, 다양한 클레임 정보를 활용한 세분화된 라우팅 정책을 구현함으로써 사용자별 맞춤형 AI 서비스를 제공할 수 있습니다.

운영 중인 AI 서비스에 JWT 인증, 클레임 기반 라우팅과 같은 기능이 필요하신가요? NGINX STORE를 통해 문의하여 F5 AI Gateway with NGINX Integration 서비스를 통해 AI 서비스를 보호하세요.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required