Workload Identity Federation

"Workload Identity Federation"(워크로드 ID 페더레이션), 즉 WIF를 사용하면 워크로드가 수명이 긴 sk-ant-... API 키 대신 단기 OpenID Connect(OIDC) 토큰으로 Claude API에 인증할 수 있습니다. 토큰은 이미 운영 중인 ID 공급자(IdP)에서 발급됩니다: AWS IAM, Google Cloud, 또는 GitHub Actions, Kubernetes, SPIFFE, Microsoft Entra ID, Okta와 같은 표준 준수 OIDC 발급자 등입니다.

워크로드는 ID 공급자가 서명한 JWT를 제시합니다. Anthropic은 Claude Console에서 구성한 신뢰 규칙에 따라 이를 검증하고, 조직 내 서비스 계정에 바인딩된 단기 Anthropic 액세스 토큰을 반환합니다. 발급하거나, CI에 저장하거나, 교체하거나, 유출될 수 있는 정적 시크릿이 없습니다.

Workload Identity Federation은 정적 API 키를 영구적이지 않고 몇 분 내에 만료되는 토큰으로 대체하여 보안 태세를 강화합니다. 다만 그 자체로 완전한 보안 솔루션은 아닙니다. 페더레이션 인증은 JWT에 서명하는 업스트림 ID 공급자만큼만 강력합니다. 심층 방어를 위해 Workload Identity Federation을 IdP가 이미 지원하는 제어 기능(워크로드 ID 바인딩, 조건부 액세스, 감사 로깅)과 함께 사용하세요.



개념

워크로드가 페더레이션을 수행하려면 먼저 Claude Console에서 세 가지 리소스를 구성해야 합니다. 이들은 함께 "발급자 X가 서명하고 Y와 같은 클레임을 가진 토큰은 서비스 계정 Z로 작동할 수 있다"를 표현합니다.



서비스 계정

서비스 계정(svac_...)은 Anthropic 조직 내의 이름이 지정된 비인간 ID입니다. 페더레이션된 토큰이 작동하는 주체(principal)입니다. 서비스 계정은 조직 수준에 존재하며, 워크스페이스의 멤버로 추가하면 해당 워크스페이스에서 활성화됩니다. 교환 시점에 Anthropic은 페더레이션 규칙의 워크스페이스가 서비스 계정의 워크스페이스 멤버십 중 하나와 일치하는지 확인합니다. 발급된 토큰은 API 키와 동일하게 해당 워크스페이스의 속도 제한과 사용량 귀속을 따릅니다. 인간 사용자와 달리 서비스 계정에는 이메일, 비밀번호, Console 로그인이 없습니다. 모든 서비스 계정은 암묵적으로 조직의 기본 워크스페이스 멤버입니다. 다른 워크스페이스에서 작동해야 하는 경우 명시적인 멤버십을 추가하세요.

API 키와의 핵심 차이점: API 키는 자격 증명 그 자체인 반면, 서비스 계정은 필요에 따라 자격 증명이 발급되는 대상입니다. 어떤 워크로드가 어떤 서비스 계정으로 작동했는지 감사할 수 있습니다.



페더레이션 발급자

페더레이션 발급자(fdis_...)는 OIDC ID 공급자를 조직에 등록합니다. 발급자를 등록하면 Anthropic에 "이 공급자가 서명한 JWT는 내 조직의 워크로드 ID를 주장할 수 있다"고 알리는 것입니다.

발급자에는 두 가지 구성 요소가 있습니다:

• 발급자 URL: 공급자의 JWT에 나타나는 정확한 iss 클레임 값입니다. 예: https://token.actions.githubusercontent.com 또는 https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• JWKS 소스: Anthropic이 JWT 서명을 검증하기 위한 공개 키를 가져오는 방법입니다. 발급자 URL에서 /.well-known/openid-configuration을 제공하는 공급자에는 discovery(기본값)를 사용하세요. JWKS 엔드포인트를 직접 가리키려면 explicit_url을 사용하고, 공용 인터넷에서 접근할 수 없는 발급자(예: 프라이빗 Kubernetes 클러스터)의 경우 키 세트를 업로드하는 inline을 사용하세요.

발급자 및 JWKS URL은 https여야 하고, 포트 443을 사용해야 하며, 공용 IP 주소로 확인되는 공용 DNS 호스트 이름을 사용해야 합니다. IP 리터럴은 허용되지 않습니다. 이러한 제약은 Anthropic이 가져오는 URL에만 적용됩니다. explicit_url 및 inline 모드에서 issuer_url은 문자열로 비교되며 내부 호스트 이름을 참조할 수 있습니다.

일반적으로 환경당 하나의 발급자를 등록합니다. 프로덕션 EKS 클러스터, 스테이징 클러스터, GitHub Actions는 세 개의 별도 발급자입니다.



페더레이션 규칙

페더레이션 규칙(fdrl_...)은 발급자와 서비스 계정 사이의 다리입니다: "발급자 X의 JWT가 Y와 같은 클레임을 가지면, 범위 S로 서비스 계정 Z에 대한 토큰을 발급한다."

규칙은 일치 조건, 대상, 그리고 규칙이 일치할 때 적용되는 권한 부여 범위와 토큰 수명을 정의합니다:

• 일치(Match): 수신 JWT가 충족해야 하는 조건입니다. subject_prefix(예: system:serviceaccount:prod:worker, 또는 접두사 일치를 위해 뒤에 * 추가), 정확한 audience, 정확한 클레임 값의 맵, 복잡한 로직을 위한 CEL condition 표현식, 또는 이들의 조합으로 일치시킬 수 있습니다. subject_prefix, claims, condition 중 최소 하나는 설정되어야 하며, JWT가 수락되려면 구성된 모든 매처를 통과해야 합니다.
• 대상(Target): 일치된 JWT가 매핑되는 서비스 계정입니다.
• 권한 부여(Authorization): 발급된 토큰에 부여되는 OAuth scope입니다. 기본값은 workspace:developer이며, 해당 워크스페이스에 발급된 API 키와 동일한 액세스 권한을 부여합니다. 일부 제품은 해당 제품의 흐름에서 규칙을 생성할 때 범위를 고정합니다. 예를 들어 MCP 터널의 터널 생성 모달은 workspace:manage_tunnels로 범위가 지정된 규칙을 생성합니다. OAuth 범위를 참조하세요. 규칙은 또한 token_lifetime_seconds(60~86400, 기본값 3600)를 설정합니다.

하나의 발급자는 여러 규칙을 가질 수 있습니다. 팀, 네임스페이스, 권한 수준별로 하나씩 만들 수 있습니다. 규칙은 ID로 평가됩니다. 클라이언트가 교환 요청에서 사용할 규칙을 지정하고, Anthropic은 JWT가 해당 규칙의 일치 기준을 충족하는지 검증합니다. 암묵적인 규칙 검색은 없습니다.



작동 방식

1. IdP가 워크로드에 JWT를 발급합니다. 대부분의 플랫폼에서 이는 자동으로 제공됩니다: Kubernetes 프로젝션된 서비스 계정 토큰, Google Cloud 메타데이터 서버, Azure IMDS, 또는 GitHub Actions OIDC 엔드포인트. JWT의 iss 클레임은 공급자를 식별하고, sub 및 기타 클레임은 특정 워크로드를 식별합니다.
2. SDK가 JWT를 Anthropic 액세스 토큰으로 교환합니다. SDK는 RFC 7523 jwt-bearer 그랜트를 사용하여 JWT를 POST /v1/oauth/token에 전송합니다. Anthropic은 발급자의 JWKS와 페더레이션 규칙의 일치 조건에 대해 JWT를 검증한 다음, 규칙의 대상 서비스 계정을 대신하여 작동하는 단기 sk-ant-oat01-... 토큰을 반환합니다.
3. SDK는 모든 요청에 토큰을 전송하고 만료 전에 갱신합니다. 애플리케이션 코드는 api_key 없이 클라이언트를 생성하고 평소처럼 API를 호출합니다. SDK는 토큰이 만료되기 전에 교환을 다시 실행합니다.



페더레이션 설정

Anthropic 조직에서 admin, owner 또는 primary owner 역할, 접근 가능한 JWKS 엔드포인트가 있는 OIDC 지원 ID 공급자(또는 에어갭 클러스터의 경우 붙여넣을 수 있는 JWKS 문서), 그리고 해당 공급자로부터 ID 토큰을 얻을 수 있는 워크로드가 필요합니다.

Connect workload 마법사는 하나의 안내된 흐름에서 세 가지 리소스(발급자, 서비스 계정, 페더레이션 규칙)를 모두 생성한 다음, 연결을 엔드투엔드로 검증합니다.

이러한 리소스를 프로그래밍 방식으로 관리하려면 curl 안내는 Admin API로 WIF 관리를 참조하고, 전체 매개변수 세부 정보와 응답 스키마는 서비스 계정 API 레퍼런스, 페더레이션 발급자 API 레퍼런스, 페더레이션 규칙 API 레퍼런스를 참조하세요.



워크로드에서 인증

페더레이션이 구성되면 워크로드는 런타임에 IdP가 발급한 JWT를 Anthropic 토큰으로 교환합니다. SDK가 교환 및 갱신 루프를 처리합니다. cURL 탭은 셸 스크립트, 디버깅 또는 SDK를 지원하지 않는 언어를 위한 기본 HTTP 교환을 보여줍니다.



SDK 클라이언트 생성

명시적 자격 증명으로 또는 인수 없이 클라이언트를 생성할 수 있습니다. 인수가 없으면 SDK는 자격 증명 우선순위에 설명된 대로 환경 변수 또는 활성 프로필에서 자격 증명을 확인합니다. 인수 없는 형태가 프로덕션 워크로드에 권장되는 패턴입니다. 동일한 컨테이너 이미지를 모든 곳에 배포하고 환경별로 ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID, ANTHROPIC_IDENTITY_TOKEN_FILE을 주입하세요.

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_...",
    ),
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

토큰 교환 응답은 RFC 6749 §5.1을 따릅니다. 필드 레퍼런스는 토큰 교환 응답을 참조하세요.



자격 증명 우선순위

모든 SDK는 동일한 5단계 순서로 자격 증명을 확인합니다: 생성자 인수, 그다음 ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, 그다음 명시적 ANTHROPIC_PROFILE, 그다음 페더레이션 환경 변수, 그다음 암묵적 활성 프로필. 자격 증명을 제공하는 첫 번째 소스가 우선합니다.

전체 우선순위 표, 단계별 의미, 프로필 파일 스키마는 WIF 레퍼런스의 자격 증명 우선순위를 참조하세요.



API 키에서 마이그레이션

기존 워크로드를 다운타임 없이 정적 API 키에서 페더레이션으로 전환하려면:

1. 페더레이션을 병렬로 구성합니다. 설정 안내를 완료하고 페더레이션 규칙이 워크로드의 토큰과 일치하는지 확인하세요. 기존 ANTHROPIC_API_KEY는 일단 그대로 둡니다.
2. 어떤 자격 증명이 선택되는지 스모크 테스트합니다. 워크로드 내부에서 ant auth status를 실행하세요(또는 SDK 디버그 로그를 확인하세요). ANTHROPIC_API_KEY가 우선순위 체인에서 페더레이션 단계보다 위에 있으므로, 이 단계에서는 여전히 API 키가 선택됩니다.
3. ANTHROPIC_API_KEY가 주입되는 모든 곳에서 설정을 해제합니다. CI 시크릿, 컨테이너 환경, 셸 프로필에서 제거하세요(앞의 경고 참조). ant auth status를 다시 실행하여 이제 페더레이션 소스가 선택되는지 확인하세요.
4. API 키를 폐기합니다. 워크로드가 페더레이션 토큰으로 실행되면 Claude Console의 Settings → API keys에서 키를 삭제하세요.



토큰 수명 및 갱신

발급된 Anthropic 토큰의 수명은 (a) 규칙의 token_lifetime_seconds(기본값 3,600초)와 (b) 제시한 IdP JWT의 남은 수명의 두 배 중 더 작은 값입니다. 결과는 60초 미만이 되지 않습니다. 두 번째 제한은 Anthropic 토큰이 파생된 업스트림 ID보다 크게 오래 살아남는 것을 방지합니다.

SDK는 토큰을 캐시하고 botocore를 모델로 한 2단계 일정으로 갱신합니다:

• 권고 갱신(Advisory refresh): 만료 120초 전. SDK가 새 교환을 시도합니다. 토큰 엔드포인트에 접근할 수 없으면 SDK는 캐시된 토큰을 계속 사용하며, 이 토큰은 약 90초 더 유효합니다.
• 필수 갱신(Mandatory refresh): 만료 30초 전. 이 시점에서 교환이 실패하면 오류가 발생합니다. 캐시된 토큰은 만료에 너무 가까워 안전하지 않습니다.

SDK는 매 교환마다 ANTHROPIC_IDENTITY_TOKEN_FILE을 다시 읽기 때문에, 교체된 프로젝션 토큰을 투명하게 반영합니다(예를 들어 Kubernetes 서비스 계정 토큰은 exp보다 훨씬 전에 교체됩니다).



ID 공급자

각 가이드는 해당 플랫폼에서 JWT가 어디에서 오는지, 클레임이 어떤 모습인지, 등록할 발급자 및 규칙 구성을 다룹니다.



참고 자료

• Admin API로 WIF 관리: 코드형 인프라에서 발급자, 서비스 계정, 규칙 생성
• WIF 레퍼런스: 환경 변수, 프로필 파일 스키마, 검증 규칙, 오류 코드
• 인증: Anthropic SDK 전반의 모든 인증 옵션
• Admin API 레퍼런스: 모든 Admin API 엔드포인트에 대한 생성된 요청 및 응답 스키마