Workload Identity Federation

"Workload Identity Federation"(워크로드 ID 페더레이션), 즉 WIF를 사용하면 워크로드가 장기간 유효한 sk-ant-... API 키 대신 단기 "OpenID Connect"(OIDC) 토큰으로 Claude API에 인증할 수 있습니다. 토큰은 이미 운영 중인 "identity provider"(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입니다. 페더레이션 토큰이 대신하여 동작하는 주체입니다. 서비스 계정은 조직 수준에 존재하며, 워크스페이스의 멤버로 추가하면 해당 워크스페이스에서 활성화됩니다. 토큰 교환 시 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].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(기본값 3600초)와 (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 엔드포인트에 대해 생성된 요청 및 응답 스키마