Claude API를 서버나 CI 파이프라인에서 쓰다 보면 결국 ANTHROPIC_API_KEY를 어딘가에 저장해야 합니다. 시크릿 매니저에 넣든, CI 환경변수로 등록하든, 이 문자열이 살아있는 한 유출 위험은 계속 남습니다. 2026년 6월 17일 정식 출시된 워크로드 아이덴티티 페더레이션(Workload Identity Federation, WIF)은 이 긴 수명의 API 키 자체를 없애는 방식으로 이 문제를 풉니다.

Anthropic Workload Identity Federation 공식 발표 이미지
이미지: claude.com

왜 필요한가

API 키는 한 번 발급되면 만료일을 걸지 않는 한 영원히 유효합니다. 이 키가 CI 로그에 찍히거나, 컨테이너 이미지에 박히거나, 누군가의 셸 히스토리에 남으면 그 순간부터 위험해집니다. AWS나 GCP에서 이미 비슷한 문제를 "워크로드 아이덴티티 페더레이션"이라는 패턴으로 풀어왔는데, 핵심은 "클라우드 플랫폼이 이미 발급해준 신원(identity)을 그대로 믿고, 그 신원을 짧게 사는 액세스 토큰으로 교환해 쓴다"는 것입니다. Anthropic이 Claude API에 적용한 WIF도 똑같은 발상입니다. GitHub Actions, Kubernetes, AWS IAM, GCP, Azure Entra ID, Okta, SPIFFE처럼 이미 쓰고 있는 신원 공급자(IdP)의 토큰을 그대로 Claude API 토큰으로 바꿔 쓰게 해줍니다. 발급·배포·회수할 긴 수명의 비밀값이 아예 사라지는 셈입니다.

핵심 개념

WIF를 쓰려면 Claude 콘솔에서 세 가지 리소스를 먼저 만들어야 합니다.

  • 서비스 계정(Service account, svac_...): 사람이 아닌 워크로드 전용 신원입니다. 이메일도 비밀번호도 없고, 조직 안에서 "이 워크로드가 누구인가"를 나타내는 주체입니다.
  • 페더레이션 발행자(Federation issuer, fdis_...): "이 OIDC 공급자가 서명한 JWT는 믿을 수 있다"고 등록하는 리소스입니다. 발행자 URL과, 서명 검증용 공개키(JWKS)를 어디서 가져올지(discovery/explicit_url/inline)를 설정합니다.
  • 페더레이션 규칙(Federation rule, fdrl_...): 발행자와 서비스 계정을 연결하는 매핑입니다. "이 발행자에서 온 JWT가 이런 클레임을 가지고 있으면, 저 서비스 계정 권한으로 토큰을 발급해라"는 조건을 subject_prefix·audience·claims·CEL 조건식으로 정의합니다. 권한 범위(oauth_scope)와 토큰 수명(token_lifetime_seconds, 기본 3,600초)도 여기서 정합니다.

실제 흐름은 이렇습니다.

  1. 워크로드가 이미 갖고 있는 IdP의 JWT를 가져옵니다(쿠버네티스 projected token, GCP 메타데이터 서버, GitHub Actions OIDC 토큰 등 플랫폼이 알아서 제공하는 경우가 대부분입니다).
  2. SDK가 이 JWT를 POST /v1/oauth/token에 보내 sk-ant-oat01-... 형태의 단기 액세스 토큰으로 교환합니다.
  3. 이후 API 요청은 이 토큰으로 인증되고, SDK가 만료 전에 자동으로 재교환합니다.

별도 베타 헤더 없이 GA 기능이고, zero-arg로 클라이언트를 생성하면 SDK가 아래 네 가지 환경변수가 전부 설정돼 있을 때 WIF를 자동으로 활성화합니다.

  • ANTHROPIC_FEDERATION_RULE_ID
  • ANTHROPIC_ORGANIZATION_ID
  • ANTHROPIC_SERVICE_ACCOUNT_ID
  • ANTHROPIC_IDENTITY_TOKEN_FILE (또는 토큰 문자열을 직접 넘기는 ANTHROPIC_IDENTITY_TOKEN)

ANTHROPIC_WORKSPACE_ID는 조건부입니다. 규칙이 워크스페이스 하나에만 적용돼 있으면 생략해도 되고, 여러 워크스페이스에 걸쳐 있으면 반드시 지정해야 합니다(생략 시 400 workspace_id_required).

실전 예시

GitHub Actions처럼 플랫폼이 OIDC 토큰을 파일로 꽂아주는 환경이라면, 코드에서 할 일은 거의 없습니다.

export ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
export ANTHROPIC_SERVICE_ACCOUNT_ID=svac_...

from anthropic import Anthropic

# API 키를 넘기지 않아도 위 환경변수만 있으면 자동으로 WIF 교환을 수행합니다.
client = Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

명시적으로 설정을 넘기고 싶다면 WorkloadIdentityCredentials를 직접 구성할 수도 있습니다.

from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile

client = Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile("/var/run/secrets/anthropic.com/token"),
        federation_rule_id="fdrl_...",
        organization_id="00000000-0000-0000-0000-000000000000",
        service_account_id="svac_...",
        workspace_id="wrkspc_...",
    ),
)

흥미로운 건 자격증명 우선순위입니다. SDK는 아래 순서로 자격증명을 찾고, 가장 먼저 발견된 것을 그대로 씁니다.

  1. 클라이언트 생성자에 직접 넘긴 값
  2. ANTHROPIC_API_KEY 또는 ANTHROPIC_AUTH_TOKEN
  3. ANTHROPIC_PROFILE로 지정한 프로필
  4. WIF 환경변수 네 가지
  5. 디스크에 저장된 활성 프로필

ANTHROPIC_API_KEY가 WIF보다 우선순위가 높다는 점이 실무에서 가장 자주 걸리는 부분입니다. 기존 워크로드를 API 키에서 WIF로 옮기는 중이라면, WIF 환경변수를 다 설정해놓고도 어딘가에 남은 ANTHROPIC_API_KEY 때문에 여전히 옛 키로 인증되는 상황이 생길 수 있습니다. ant auth status로 실제 어떤 자격증명이 이기고 있는지 먼저 확인하고, 컨테이너 환경·CI 시크릿·셸 프로필 전부에서 키를 지워야 전환이 끝납니다. 빈 문자열(ANTHROPIC_API_KEY="")도 우선순위 자리를 차지한다는 점도 주의할 부분입니다 — 반드시 unset해야 합니다.

토큰 수명과 보안 쪽 디테일

발급되는 토큰 수명은 "규칙에 설정된 token_lifetime_seconds(기본 1시간)"와 "제시한 IdP JWT의 남은 수명의 2배" 중 더 짧은 쪽을 따릅니다. 즉 상위 신원보다 오래 사는 토큰은 절대 나오지 않습니다. SDK는 만료 120초 전에 미리 재교환을 시도하고(실패해도 캐시된 토큰으로 버팀), 30초 전에는 반드시 재교환에 성공해야 합니다.

jti 클레임이 있는 JWT는 발행자별로 단 한 번만 교환할 수 있습니다. 같은 토큰을 재시도 루프에서 두 번 보내면 jti_reused로 거부되는데, 재시도 로직을 짤 때 자주 놓치는 지점입니다. 실패 사유는 API 응답에는 나오지 않고(모든 거부가 동일한 401 Authentication failed로만 돌아옵니다 — 공격자가 설정을 역추적하지 못하게 하려는 설계입니다), 콘솔의 인증 기록 페이지에서만 확인할 수 있습니다.

언제 쓸 만한가

로컬 개발이나 간단한 스크립트에는 여전히 API 키가 더 간단합니다. WIF가 값을 발휘하는 지점은 프로덕션 워크로드, CI/CD 파이프라인, 쿠버네티스처럼 "플랫폼이 이미 신원을 발급해주고 있는" 환경입니다. 이런 곳에서는 Claude API용 비밀값을 따로 관리할 필요가 없어지고, 어떤 워크로드가 어떤 서비스 계정으로 호출했는지 감사 기록도 더 명확하게 남습니다. 다만 WIF 자체가 보안을 완성해주는 건 아닙니다. 신뢰 사슬의 출발점은 결국 IdP이고, 그 IdP 토큰을 발급하는 더 상위의 장기 자격증명(예: 정적 클라우드 크리덴셜)이 뚫리면 WIF로 바꾼 의미도 함께 사라집니다. IP allowlist, MFA, 감사 로깅 같은 기존 통제는 그대로 같이 가져가야 합니다.