SPIFFE와 함께 WIF 사용하기

SPIFFE는 워크로드에 ID를 발급하기 위한 CNCF 표준입니다. SPIRE는 이에 대한 오픈소스 참조 구현이며, 여러 상용 제품도 SPIFFE 호환 ID를 발급합니다. Anthropic은 OIDC 호환 JWT-SVID를 발급하는 모든 SPIFFE 구현과 페더레이션합니다. 페더레이션은 공개 HTTPS URL의 OIDC 디스커버리 문서를 통해(discovery 모드, URL 제약 조건 참조) 또는 JWKS를 직접 등록하여(inline 모드) 작동합니다. JWT-SVID 사양은 sub를 워크로드의 SPIFFE ID로 정의하며, SPIFFE Workload API는 호출자가 가져오기 시점에 aud를 제공하도록 요구하므로 이러한 클레임은 구현 전반에서 동일합니다. Anthropic은 추가로 iss와 iat를 요구하는데, 이 둘은 JWT-SVID 사양에서 필수가 아니므로 구현에서 둘 다 채우도록 구성하세요(SPIRE에서 iss는 jwt_issuer 서버 설정이며 iat는 자동으로 설정됩니다). 이러한 설정이 완료되면 이 가이드의 Anthropic 구성, 토큰 획득 및 사용, 규칙 범위 지정 섹션이 모든 SPIFFE 구현에 적용됩니다. 최신 목록은 SPIFFE 프로젝트 사이트의 SPIFFE를 구현하는 상용 소프트웨어를 참조하세요.

SPIFFE는 모든 워크로드에 spiffe://<trust-domain>/<path> 형식의 안정적인 ID URI를 할당하며, SPIRE는 Workload API를 통해 요청 시 해당 ID를 JWT-SVID로 발급합니다. JWT-SVID는 sub 클레임이 워크로드의 SPIFFE ID이고 aud 클레임이 가져오기 시점에 워크로드에 의해 제공되는 일반적인 서명된 JWT입니다.

SPIRE 트러스트 도메인에서 표준 OIDC로의 브리지는 SPIRE OIDC Discovery Provider로, 트러스트 도메인의 JWT 서명 키에 대한 /.well-known/openid-configuration 및 JWKS 엔드포인트를 게시하는 독립 실행형 헬퍼입니다. 디스커버리 프로바이더가 실행 중이면 JWT-SVID는 다른 OIDC 토큰과 마찬가지로 검증됩니다. 디스커버리 URL을 페더레이션 발급자로 등록하고, 워크로드의 SPIFFE ID와 일치하는 페더레이션 규칙을 작성한 다음, 워크로드가 Anthropic의 토큰 교환 엔드포인트에 JWT-SVID를 제시하도록 하세요.

이 페이지의 예제는 SPIRE를 사용하며 SPIRE Agent가 실행되는 모든 곳(Kubernetes 파드, 가상 머신, 베어메탈 호스트)에 적용됩니다.

사전 요구 사항

• WIF 개념에 대한 이해: 서비스 계정, 페더레이션 발급자, 페더레이션 규칙.
• 워크로드 ID가 발급된 SPIFFE 배포(이 페이지의 예제는 SPIRE Server 및 Agent를 사용함)와 Claude API를 호출해야 하는 워크로드에 대한 등록 항목.
• 트러스트 도메인에 대한 OIDC 디스커버리 엔드포인트(SPIRE의 경우 OIDC Discovery Provider)가 공개적으로 접근 가능한 HTTPS 엔드포인트로 실행 중이거나, inline 등록을 위해 내보낸 JWKS.
• JWT-SVID의 iss 클레임을 페더레이션 발급자의 issuer_url로 등록할 값으로 설정하도록 구성된 SPIFFE 발급자. discovery 모드의 경우 이는 디스커버리 엔드포인트의 공개 URL입니다(SPIRE의 경우 jwt_issuer 서버 설정).
• 워크로드에서 사용 가능한 JWT-SVID. WIF는 JWT-SVID만 허용하며 X.509-SVID는 사용되지 않습니다.
• Anthropic 조직의 Claude Console에서 서비스 계정, 페더레이션 발급자, 페더레이션 규칙을 생성할 수 있는 권한.

JWT-SVID를 가져올 때 요청할 audience 값은 항상 https://api.anthropic.com입니다. 이 값을 spiffe-helper의 jwt_audience, Workload API FetchJWTSVID 호출, 페더레이션 규칙의 audience 매처에 사용하세요.

SPIRE 구성

이 섹션의 지침은 SPIRE에 특화되어 있습니다. 다른 SPIFFE 발급자를 사용하는 경우 해당 문서에 따라 OIDC 디스커버리 엔드포인트와 JWT-SVID 검색을 구성한 다음 Anthropic 구성으로 계속 진행하세요.

이미 OIDC Discovery Provider와 함께 SPIRE를 실행 중인 경우, Anthropic과 페더레이션하려면 SPIRE 측에서 세 가지가 필요합니다. 디스커버리 URL과 일치하는 jwt_issuer, Claude API를 호출할 워크로드에 대한 등록 항목, 그리고 해당 워크로드가 Anthropic audience로 JWT-SVID를 가져올 수 있는 방법입니다. 다음 하위 섹션에서 각각을 안내합니다. 구성 스니펫은 Anthropic 페더레이션과 관련된 설정만 보여주며 완전한 SPIRE 배포 구성이 아닙니다.

JWT 발급자 확인

Anthropic은 JWT-SVID의 iss 클레임을 등록된 페더레이션 발급자와 대조하고 해당 발급자의 디스커버리 문서에서 JWKS를 가져와 JWT-SVID를 검증합니다. 두 SPIRE 설정이 동일한 URL에 대해 일치해야 합니다. SPIRE Server의 jwt_issuer(발급되는 모든 JWT-SVID의 iss 클레임이 됨)와 OIDC Discovery Provider의 domains 목록(디스커버리 문서와 JWKS가 제공되는 호스트를 결정함)입니다. 이 공유 URL이 Anthropic에 등록하는 값입니다.

트러스트 도메인과 발급자 URL은 독립적입니다. 트러스트 도메인(spiffe://prod.example.com)은 sub 클레임의 범위를 지정하고, 발급자 URL(https://oidc-discovery.prod.example.com)은 Anthropic이 서명 키를 가져오는 위치입니다. 이 둘은 호스트 이름을 공유할 필요가 없습니다.

SPIRE Server의 구성에서 jwt_issuer가 설정되어 있고 디스커버리 프로바이더의 공개 URL을 가리키는지 확인하세요. 다음 예제는 기본 JWT-SVID 수명도 보여줍니다. SPIRE의 기본 제공 기본값은 5분으로, 지속적인 로테이션이 필요할 만큼 짧습니다(spiffe-helper 실행 참조). Anthropic의 토큰 교환 엔드포인트는 수명이 페더레이션 발급자의 구성된 최대값(기본적으로 1시간, 검증 규칙 참조)을 초과하는 모든 ID 토큰을 거부합니다. 이 검사는 SPIRE뿐만 아니라 모든 SPIFFE 구현에 적용되므로 default_jwt_svid_ttl(또는 항목별 재정의)을 해당 최대값 이하로 유지하세요.

server {
    trust_domain         = "prod.example.com"
    jwt_issuer           = "https://oidc-discovery.prod.example.com"
    default_jwt_svid_ttl = "5m"
    # ...
}

OIDC Discovery Provider의 구성에서 동일한 호스트 이름이 domains 아래에 나타나야 하며, 프로바이더는 SPIRE Server의 API 소켓에 접근할 수 있어야 합니다. 프로바이더는 HTTPS를 통해 디스커버리 문서와 JWKS를 제공합니다. 내장 ACME 지원으로 TLS를 종료하거나 이를 수행하는 로드 밸런서를 앞에 배치하세요.

domains = ["oidc-discovery.prod.example.com"]

server_api {
    address = "unix:///run/spire/sockets/private/api.sock"
}

acme {
    email        = "[email protected]"
    tos_accepted = true
}

워크로드 등록

Claude API를 호출하는 각 워크로드에는 런타임 셀렉터를 SPIFFE ID에 매핑하는 SPIRE 등록 항목이 필요합니다. 워크로드가 이미 등록되어 있다면 해당 SPIFFE ID를 기록해 두세요. 페더레이션 규칙의 subject_prefix에서 사용합니다. 등록되어 있지 않다면 등록하세요. Kubernetes 파드의 경우 셀렉터는 일반적으로 네임스페이스와 Kubernetes 서비스 계정입니다.

spire-server entry create \
    -spiffeID spiffe://prod.example.com/ns/inference/sa/worker \
    -parentID spiffe://prod.example.com/spire/agent/k8s_psat/prod-cluster/NODE_UID \
    -selector k8s:ns:inference \
    -selector k8s:sa:worker

Kubernetes 외부의 워크로드는 unix:uid:1000과 같은 호스트 수준 셀렉터를 사용합니다(unix:path도 사용 가능하지만 에이전트의 unix 워크로드 어테스터 구성에서 discover_workload_path = true가 필요함). spire-controller-manager를 실행하는 클러스터는 spire-server entry create를 직접 호출하는 대신 ClusterSPIFFEID 커스텀 리소스로 항목을 선언할 수 있습니다.

spiffe-helper 실행

spiffe-helper는 SPIRE Agent 소켓에 연결하여 지정된 audience에 대한 JWT-SVID를 가져오고, 파일에 쓰고, 만료 전에 다시 가져오는 사이드카 유틸리티입니다. 헬퍼는 기본적으로 데몬 모드로 실행되며, 아래 예제는 daemon_mode = true를 명시적으로 설정합니다.

agent_address = "/run/spire/sockets/agent.sock"
cert_dir      = "/var/run/secrets/anthropic.com"
daemon_mode   = true

jwt_svids = [{
    jwt_audience       = "https://api.anthropic.com"
    jwt_svid_file_name = "token"
}]

Kubernetes에서는 베어러 SVID가 노드의 디스크에 저장되지 않도록 애플리케이션 컨테이너와 메모리 기반 emptyDir 볼륨(medium: Memory)을 공유하는 사이드카 컨테이너로 spiffe-helper를 실행하세요. 호스트의 SPIRE Agent 소켓을 사이드카에 마운트하고, 공유 볼륨을 두 컨테이너 모두에서 /var/run/secrets/anthropic.com에 마운트한 다음, 애플리케이션 컨테이너에 ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token을 설정하세요. VM 및 베어메탈에서는 spiffe-helper를 워크로드와 함께 시스템 서비스로 실행하고 둘 다 공유 디렉터리를 가리키도록 하세요.

Anthropic 구성

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

페더레이션 발급자: OIDC Discovery Provider의 공개 URL을 discovery 모드로 등록하세요. Anthropic은 이 URL에서 /.well-known/openid-configuration을 가져오고 반환된 jwks_uri를 따라 트러스트 도메인의 서명 키를 검색합니다.

{
  "name": "spire-prod",
  "issuer_url": "https://oidc-discovery.prod.example.com",
  "jwks": { "type": "discovery" }
}

디스커버리 프로바이더가 공개 인터넷에서 접근할 수 없는 경우, JWKS를 직접 가져와서(curl https://oidc-discovery.prod.example.com/keys) 반환된 keys 배열의 내용을 사용하여 "jwks": {"type": "inline", "keys": [...]}로 발급자를 등록하세요. inline 모드에서 issuer_url은 JWT-SVID의 iss 클레임과 비교되는 용도로만 사용되며, Anthropic은 해당 URL에 접근을 시도하지 않습니다.

공개 디스커버리 엔드포인트를 노출하지 않고 JWKS 업데이트를 자동화하려면, SPIRE Server BundlePublisher 플러그인(aws_s3, gcp_cloudstorage 또는 k8s_configmap)을 format = "jwks"로 구성하여 로테이션마다 JWT 서명 키를 외부 스토리지로 푸시한 다음, 이를 발급자의 인라인 키에 동기화하세요.

페더레이션 규칙: JWT-SVID의 sub(SPIFFE ID)와 spiffe-helper가 요청하도록 구성한 aud를 매칭하세요. SPIFFE ID는 URI 문자열이며 subject_prefix는 이를 불투명 텍스트로 매칭하므로, 정확한 값 또는 후행 * 접두사 매칭 모두 작동합니다. 더 복잡한 패턴의 경우 CEL condition을 사용하세요.

{
  "name": "spire-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "spiffe://prod.example.com/ns/inference/sa/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를 spiffe://prod.example.com/ns/inference/*로 완화하세요. 규칙의 fdrl_... ID를 워크로드의 ANTHROPIC_FEDERATION_RULE_ID 환경 변수에 추가하세요.

토큰 획득 및 사용

Anthropic SDK는 spiffe-helper가 유지 관리하는 파일에서 JWT-SVID를 읽거나 토큰 프로바이더 콜러블을 통해 SPIFFE Workload API를 직접 호출할 수 있습니다. 파일 경로 방식은 가장 간단한 통합이며 모든 SDK 언어에서 작동합니다. 콜러블 방식은 사이드카를 제거하지만 애플리케이션 언어에 SPIFFE Workload API 클라이언트가 필요합니다.

설정 확인

SDK를 연결하기 전에 SPIRE Agent에서 직접 JWT-SVID를 가져와 클레임이 페더레이션 규칙이 기대하는 것과 일치하는지 확인하세요. 다른 SPIFFE 구현을 사용하는 경우 해당 CLI 또는 Workload API 클라이언트로 JWT-SVID를 가져와 동일한 방식으로 페이로드를 디코딩하세요.

spire-agent api fetch jwt \
    -audience https://api.anthropic.com \
    -socketPath /run/spire/sockets/agent.sock \
    -output json \
  | jq -r '.[0].svids[0].svid' \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

-output json 플래그는 SVID 응답과 번들 응답을 두 요소 JSON 배열로 반환하므로 jq -r '.[0].svids[0].svid'가 순수 토큰을 추출합니다. -output이 없는 이전 SPIRE 버전에서는 명령이 레이블이 지정된 블록을 대신 출력합니다. 이 경우 기본 출력을 awk '/^[[:space:]]*eyJ/{print $1; exit}'로 파이프하여 토큰 줄을 추출하세요. iss가 등록한 OIDC Discovery Provider URL인지, sub가 워크로드의 SPIFFE ID인지, aud에 https://api.anthropic.com이 포함되어 있는지 확인하세요. 그런 다음 토큰 획득 및 사용의 cURL 예제를 실행하세요. 교환이 성공하면 sk-ant-oat01-로 시작하는 access_token이 반환됩니다. 400 invalid_grant가 발생하면 실패한 교환 문제 해결을 참조하세요. SPIRE 측에서 가장 흔한 원인은 SPIRE Server의 jwt_issuer와 페더레이션 발급자로 등록된 URL 간의 불일치입니다.

규칙 범위 지정

SPIFFE ID 경로 규칙은 운영자가 정의하므로, 페더레이션 규칙의 subject_prefix 매처는 등록 항목이 사용하는 경로 체계를 반영해야 합니다. 일반적인 체계로는 spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>(spire-controller-manager의 ClusterSPIFFEID 리소스가 내보내는 기본값)와 VM 및 베어메탈 워크로드를 위한 spiffe://<trust-domain>/host/<hostname>/<service>가 있습니다.

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

• 하나의 워크로드에 고정: subject_prefix를 후행 * 없이 전체 SPIFFE ID로 설정하세요.
• 항상 audience 설정: 규칙에 audience를 필수로 지정하고 spiffe-helper(또는 Workload API 호출)를 동일한 값으로 구성하여 다른 신뢰 당사자를 위해 발급된 SVID가 거부되도록 하세요.
• 경로 세그먼트별 범위 지정: spiffe://prod.example.com/ns/inference/*를 사용하여 네임스페이스 아래에 등록된 모든 워크로드에 권한을 부여하고, 하나의 규칙을 확장하는 대신 네임스페이스별로 별도의 규칙과 Anthropic 서비스 계정을 생성하세요.
• 트러스트 도메인당 하나의 발급자: 각 SPIRE 트러스트 도메인에는 자체 서명 키와 OIDC Discovery Provider가 있습니다. 각각을 별도의 페더레이션 발급자로 등록하고 규칙을 해당 규칙이 매칭하는 SPIFFE ID를 소유한 발급자에 바인딩하세요.

다음 단계

• Workload Identity Federation: 개념, 토큰 교환 흐름, SDK 구성 옵션.
• WIF 참조: 환경 변수, JWKS 소스 모드, 규칙 매칭 모드.
• Kubernetes와 함께 WIF 사용하기: SPIRE 대신 네이티브 프로젝티드 서비스 계정 토큰을 사용하는 클러스터용.