관리자ID 공급자

Kubernetes에서 WIF 사용하기

프로젝티드 서비스 계정 토큰을 사용하여 자체 관리형 Kubernetes 클러스터에서 Claude API에 인증합니다.

자체 관리형 Kubernetes 클러스터(kubeadm, k3s, OpenShift 및 온프레미스 배포판)는 프로젝티드 서비스 계정 토큰을 통해 모든 파드에 대해 OIDC "JSON Web Token"(JSON 웹 토큰), 즉 JWT에 서명합니다. 클러스터의 API 서버가 OIDC 발급자 역할을 하며, 각 토큰의 sub 클레임은 system:serviceaccount:<namespace>:<service-account> 형식을 따릅니다. 클러스터의 디스커버리 문서를 읽어 발급자 URL을 확인할 수 있습니다.

cURL

kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

이 페이지에서 설명하는 메커니즘(프로젝티드 서비스 계정 토큰, OIDC 발급자로서의 클러스터 API 서버)은 Kubernetes 자체에 내장된 기능이므로 모든 Kubernetes 배포판의 기반이 됩니다. 관리형 Kubernetes 서비스에서 실행하는 경우, 클라우드 제공업체 가이드에서 제공업체가 관리하는 발급자 URL을 찾는 방법을 안내합니다: AWS (EKS), Google Cloud (GKE), Azure (AKS). 클러스터에서 SPIRE를 실행하는 경우, 클러스터 API 서버가 아닌 SPIRE OIDC Discovery Provider가 발급자입니다. SPIFFE를 참조하세요. 그 외의 배포판이나 목록에 없는 관리형 제공업체의 경우, 이 가이드를 따르고 클러스터가 보고하는 발급자 URL을 사용하세요.

사전 요구 사항

WIF 개념에 대한 이해: 서비스 계정, 페더레이션 발급자, 페더레이션 규칙.
API 서버에 --service-account-issuer 플래그가 구성된 Kubernetes 클러스터. 대부분의 배포판은 기본적으로 이를 설정하며, kubeadm 클러스터는 일반적으로 https://kubernetes.default.svc.cluster.local을 사용합니다. API 서버 구성에 직접 접근할 수 없는 경우 플랫폼 팀에서 값을 확인할 수 있습니다.
Anthropic이 토큰 서명을 검증할 수 있도록 다음 중 하나가 필요합니다.
- 발급자의 JWKS 엔드포인트가 포트 443의 HTTPS를 통해 공용 인터넷에서 접근 가능하거나,
- 클러스터 내부에서 JWKS를 가져와 inline 모드로 등록할 수 있어야 합니다(Anthropic 구성에서 다룸).
Anthropic 조직의 Claude Console에서 서비스 계정, 페더레이션 발급자, 페더레이션 규칙을 생성할 수 있는 권한.

Kubernetes 구성

페더레이션 규칙이 기대하는 audience와 수명으로 서비스 계정 토큰을 파드에 프로젝션하세요. serviceAccountToken 프로젝션은 마운트 경로에 새 JWT를 작성하고 expirationSeconds가 경과하기 전에 이를 교체합니다.

Pod

apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
spec:
  serviceAccountName: inference-worker
  volumes:
    - name: anthropic-token
      projected:
        sources:
          - serviceAccountToken:
              audience: https://api.anthropic.com
              expirationSeconds: 3600
              path: token
  containers:
    - name: app
      image: your-registry/inference-worker:latest
      env:
        - name: ANTHROPIC_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/anthropic.com/token
        - name: ANTHROPIC_FEDERATION_RULE_ID
          value: fdrl_...
        - name: ANTHROPIC_ORGANIZATION_ID
          value: 00000000-0000-0000-0000-000000000000
        - name: ANTHROPIC_SERVICE_ACCOUNT_ID
          value: svac_...
        - name: ANTHROPIC_WORKSPACE_ID  # required when the rule covers multiple workspaces
          value: wrkspc_...
      volumeMounts:
        - name: anthropic-token
          mountPath: /var/run/secrets/anthropic.com
          readOnly: true

이 파드에 대해 발급된 토큰은 sub: "system:serviceaccount:inference:inference-worker"와 aud: ["https://api.anthropic.com"]를 포함합니다.

Anthropic 구성

설정 안내를 따라 Claude Console에서 페더레이션 발급자를 등록하고, Anthropic 서비스 계정을 생성하고, 페더레이션 규칙을 생성하세요. 다음 Kubernetes 관련 값을 사용하세요.

페더레이션 발급자: 많은 자체 관리형 클러스터는 공용 인터넷에서 접근할 수 없는 https://kubernetes.default.svc.cluster.local과 같은 발급자 URL을 사용합니다. 클러스터가 이에 해당하는 경우, inline JWKS 소스를 선택하고 클러스터의 키를 붙여넣으세요. 클러스터 내부에서 키를 가져오세요.

cURL

kubectl get --raw /openid/v1/jwks

그런 다음 반환된 keys 배열의 내용(이를 감싸는 {"keys": [...]} 래퍼가 아님)으로 발급자를 구성하세요.

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks_source": "inline",
  "jwks_keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
}

inline 모드에서 issuer_url은 JWT의 iss 클레임과 비교하는 데만 사용되며, Anthropic은 해당 URL에 접근을 시도하지 않습니다. 발급자가 공개적으로 접근 가능한 경우, 대신 "jwks_source": "discovery"를 사용하고 jwks_keys를 생략하세요.

inline 키를 사용하는 경우, 클러스터가 서비스 계정 서명 키를 교체할 때 발급자를 업데이트할 책임은 사용자에게 있습니다. 교체는 드물게 발생하지만(일반적으로 클러스터 업그레이드 중에만), 새 JWKS를 푸시할 때까지 토큰 교환은 서명 오류로 실패합니다.

페더레이션 규칙: 서비스 계정의 sub 클레임과 프로젝티드 토큰에 설정한 audience를 매칭하세요.

{
  "name": "onprem-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "system:serviceaccount:inference:inference-worker",
    "audience": "https://api.anthropic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

워크로드가 허용하는 한 최대한 구체적으로 설정하세요. 네임스페이스의 모든 서비스 계정이 동일한 Anthropic 서비스 계정에 매핑되어야 하는 경우에만 subject_prefix를 system:serviceaccount:inference:*(후행 *는 접두사 매칭을 의미함)로 완화하세요. 규칙의 fdrl_... ID를 파드의 ANTHROPIC_FEDERATION_RULE_ID 환경 변수에 추가하세요.

토큰 획득 및 사용

Kubernetes 구성의 파드 스펙은 ANTHROPIC_IDENTITY_TOKEN_FILE을 프로젝티드 마운트 경로로 설정하고, ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID도 함께 설정합니다. 이러한 설정이 완료되면 SDK는 매 교환 시 디스크에서 토큰을 읽고 Anthropic 액세스 토큰을 자동으로 갱신합니다.

import anthropic

# ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID를
# 파드의 환경에서 읽어옵니다.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

설정 확인

교환이 성공하면 sk-ant-oat01-로 시작하는 access_token과 초 단위의 expires_in 값이 반환됩니다. 400 invalid_grant 오류가 발생하면 실패한 교환 문제 해결을 참조하세요. Kubernetes 측에서 가장 흔한 원인은 JWKS 키 불일치입니다(inline 모드의 경우 kubectl get --raw /openid/v1/jwks로 다시 가져와 발급자를 업데이트하세요).

규칙 범위 지정

subject_prefix가 system:serviceaccount:*인 경우 클러스터의 모든 서비스 계정과 매칭되므로, 모든 파드가 페더레이션된 Anthropic 토큰을 획득할 수 있습니다. audience 매처가 없으면 규칙은 모든 파드에 이미 프로젝션되어 있는 클러스터의 기본 audience 토큰과도 매칭됩니다.

규칙의 match 블록을 사용 사례에 맞는 가장 좁은 범위로 제한하세요.

네임스페이스와 서비스 계정 이름 고정: 후행 * 없이 전체 system:serviceaccount:<namespace>:<name> 값을 사용하세요.
항상 audience 설정: 규칙에 audience를 필수로 지정하고 파드의 serviceAccountToken 프로젝션에 동일한 값을 설정하여 기본 audience 토큰이 거부되도록 하세요.
네임스페이스별로 별도 규칙 사용: 하나의 규칙을 확장하는 대신 각 네임스페이스에 대해 별도의 규칙과 Anthropic 서비스 계정을 생성하세요.
inline JWKS 발급자를 하나의 클러스터로 범위 지정: 여러 클러스터가 발급자 URL을 공유하는 경우, 각 클러스터의 JWKS를 자체 페더레이션 발급자로 등록하고 규칙을 해당 발급자에만 바인딩하세요.

다음 단계

Workload Identity Federation: 개념, 토큰 교환 흐름, SDK 구성 옵션.
WIF 참조: 환경 변수, JWKS 소스 모드, 규칙 매칭 모드.

Was this page helpful?

관리자ID 공급자

Kubernetes에서 WIF 사용하기

프로젝티드 서비스 계정 토큰을 사용하여 자체 관리형 Kubernetes 클러스터에서 Claude API에 인증합니다.

cURL

kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

사전 요구 사항

WIF 개념에 대한 이해: 서비스 계정, 페더레이션 발급자, 페더레이션 규칙.
API 서버에 --service-account-issuer 플래그가 구성된 Kubernetes 클러스터. 대부분의 배포판은 기본적으로 이를 설정하며, kubeadm 클러스터는 일반적으로 https://kubernetes.default.svc.cluster.local을 사용합니다. API 서버 구성에 직접 접근할 수 없는 경우 플랫폼 팀에서 값을 확인할 수 있습니다.
Anthropic이 토큰 서명을 검증할 수 있도록 다음 중 하나가 필요합니다.
- 발급자의 JWKS 엔드포인트가 포트 443의 HTTPS를 통해 공용 인터넷에서 접근 가능하거나,
- 클러스터 내부에서 JWKS를 가져와 inline 모드로 등록할 수 있어야 합니다(Anthropic 구성에서 다룸).
Anthropic 조직의 Claude Console에서 서비스 계정, 페더레이션 발급자, 페더레이션 규칙을 생성할 수 있는 권한.

Kubernetes 구성

Pod

apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
spec:
  serviceAccountName: inference-worker
  volumes:
    - name: anthropic-token
      projected:
        sources:
          - serviceAccountToken:
              audience: https://api.anthropic.com
              expirationSeconds: 3600
              path: token
  containers:
    - name: app
      image: your-registry/inference-worker:latest
      env:
        - name: ANTHROPIC_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/anthropic.com/token
        - name: ANTHROPIC_FEDERATION_RULE_ID
          value: fdrl_...
        - name: ANTHROPIC_ORGANIZATION_ID
          value: 00000000-0000-0000-0000-000000000000
        - name: ANTHROPIC_SERVICE_ACCOUNT_ID
          value: svac_...
        - name: ANTHROPIC_WORKSPACE_ID  # required when the rule covers multiple workspaces
          value: wrkspc_...
      volumeMounts:
        - name: anthropic-token
          mountPath: /var/run/secrets/anthropic.com
          readOnly: true

이 파드에 대해 발급된 토큰은 sub: "system:serviceaccount:inference:inference-worker"와 aud: ["https://api.anthropic.com"]를 포함합니다.

Anthropic 구성

cURL

kubectl get --raw /openid/v1/jwks

그런 다음 반환된 keys 배열의 내용(이를 감싸는 {"keys": [...]} 래퍼가 아님)으로 발급자를 구성하세요.

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks_source": "inline",
  "jwks_keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
}

페더레이션 규칙: 서비스 계정의 sub 클레임과 프로젝티드 토큰에 설정한 audience를 매칭하세요.

{
  "name": "onprem-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "system:serviceaccount:inference:inference-worker",
    "audience": "https://api.anthropic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

토큰 획득 및 사용

import anthropic

# ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID를
# 파드의 환경에서 읽어옵니다.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

설정 확인

규칙 범위 지정

규칙의 match 블록을 사용 사례에 맞는 가장 좁은 범위로 제한하세요.

네임스페이스와 서비스 계정 이름 고정: 후행 * 없이 전체 system:serviceaccount:<namespace>:<name> 값을 사용하세요.
항상 audience 설정: 규칙에 audience를 필수로 지정하고 파드의 serviceAccountToken 프로젝션에 동일한 값을 설정하여 기본 audience 토큰이 거부되도록 하세요.
네임스페이스별로 별도 규칙 사용: 하나의 규칙을 확장하는 대신 각 네임스페이스에 대해 별도의 규칙과 Anthropic 서비스 계정을 생성하세요.
inline JWKS 발급자를 하나의 클러스터로 범위 지정: 여러 클러스터가 발급자 URL을 공유하는 경우, 각 클러스터의 JWKS를 자체 페더레이션 발급자로 등록하고 규칙을 해당 발급자에만 바인딩하세요.

다음 단계

Workload Identity Federation: 개념, 토큰 교환 흐름, SDK 구성 옵션.
WIF 참조: 환경 변수, JWKS 소스 모드, 규칙 매칭 모드.

Was this page helpful?