관리자인증

Workload Identity Federation

장기간 유효한 정적 API 키 대신 자체 ID 공급자에서 발급한 단기 ID 토큰으로 Claude API에 워크로드를 인증합니다.

"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를 주장할 수 있다"고 알리는 것입니다.

발급자에는 두 가지 구성 항목이 있습니다.

Issuer URL: 공급자의 JWT에 나타나는 정확한 iss 클레임 값입니다. 예: https://token.actions.githubusercontent.com 또는 https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
JWKS source: 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 터널의 터널 생성 모달은 org:manage_tunnels로 스코프가 지정된 규칙을 생성합니다. OAuth 스코프를 참조하세요. 규칙은 또한 token_lifetime_seconds(60~86400, 기본값 3600)를 설정합니다.

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

작동 방식

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

페더레이션 설정

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

Claude Console에서 Settings → Workload identity로 이동하세요.

워크로드에서 인증

페더레이션이 구성되면 워크로드는 런타임에 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을 주입하세요.

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

자격 증명 우선순위

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

ANTHROPIC_API_KEY는 페더레이션 단계보다 위에 있으므로, 환경에 남아 있는 키가 페더레이션을 조용히 가립니다. 워크로드를 API 키에서 Workload Identity Federation으로 마이그레이션할 때는 해당 워크로드가 실행되는 모든 곳(컨테이너 환경, CI 시크릿, 셸 프로필)에서 ANTHROPIC_API_KEY가 설정 해제되었는지 확인하세요. CLI의 ant auth status 명령은 어떤 소스가 선택되었는지 보고합니다.

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

API 키에서 마이그레이션

다운타임 없이 기존 워크로드를 정적 API 키에서 페더레이션으로 전환하려면 다음을 수행하세요.

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

토큰 수명 및 갱신

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

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

권고 갱신은 만료 120초 전에 수행됩니다. SDK는 새 교환을 시도합니다. 토큰 엔드포인트에 접근할 수 없는 경우 SDK는 캐시된 토큰을 계속 제공하며, 이 토큰은 약 90초 동안 더 유효합니다.
필수 갱신은 만료 30초 전에 수행됩니다. 이 시점에서 교환이 실패하면 오류가 발생합니다. 캐시된 토큰은 만료가 너무 임박하여 안전하지 않습니다.

SDK는 교환할 때마다 ANTHROPIC_IDENTITY_TOKEN_FILE을 다시 읽으므로 교체된 프로젝티드 토큰을 투명하게 가져옵니다(예를 들어 Kubernetes 서비스 계정 토큰은 exp보다 훨씬 전에 교체됩니다).

ID 공급자

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

AWS

STS 웹 ID 토큰 또는 EKS IRSA 프로젝티드 토큰.

Google Cloud

메타데이터 서버에서 Google이 서명한 ID 토큰.

Microsoft Azure

Managed Identity(IMDS) 및 AKS의 Entra Workload ID.

참고 항목

WIF 참조: 환경 변수, 프로필 파일 스키마, 검증 규칙, 오류 코드
인증: Anthropic SDK 전반의 모든 인증 옵션

Was this page helpful?

관리자인증

Workload Identity Federation

장기간 유효한 정적 API 키 대신 자체 ID 공급자에서 발급한 단기 ID 토큰으로 Claude API에 워크로드를 인증합니다.

개념

서비스 계정

페더레이션 발급자

발급자에는 두 가지 구성 항목이 있습니다.

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

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

페더레이션 규칙

규칙은 매치 조건, 대상, 그리고 규칙이 매치될 때 적용되는 권한 부여 스코프 및 토큰 수명을 정의합니다.

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 터널의 터널 생성 모달은 org:manage_tunnels로 스코프가 지정된 규칙을 생성합니다. OAuth 스코프를 참조하세요. 규칙은 또한 token_lifetime_seconds(60~86400, 기본값 3600)를 설정합니다.

작동 방식

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

페더레이션 설정

Claude Console에서 Settings → Workload identity로 이동하세요.

워크로드에서 인증

SDK 클라이언트 구성

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

자격 증명 우선순위

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

API 키에서 마이그레이션

다운타임 없이 기존 워크로드를 정적 API 키에서 페더레이션으로 전환하려면 다음을 수행하세요.

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

토큰 수명 및 갱신

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

권고 갱신은 만료 120초 전에 수행됩니다. SDK는 새 교환을 시도합니다. 토큰 엔드포인트에 접근할 수 없는 경우 SDK는 캐시된 토큰을 계속 제공하며, 이 토큰은 약 90초 동안 더 유효합니다.
필수 갱신은 만료 30초 전에 수행됩니다. 이 시점에서 교환이 실패하면 오류가 발생합니다. 캐시된 토큰은 만료가 너무 임박하여 안전하지 않습니다.

ID 공급자

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

AWS

STS 웹 ID 토큰 또는 EKS IRSA 프로젝티드 토큰.

Google Cloud

메타데이터 서버에서 Google이 서명한 ID 토큰.

Microsoft Azure

Managed Identity(IMDS) 및 AKS의 Entra Workload ID.

참고 항목

WIF 참조: 환경 변수, 프로필 파일 스키마, 검증 규칙, 오류 코드
인증: Anthropic SDK 전반의 모든 인증 옵션

Was this page helpful?

필드	값
Name	참조용 레이블입니다. 예: `prod-eks` 또는 `gha`. 소문자, 숫자, 하이픈만 사용 가능합니다.
Issuer URL	IdP가 JWT에 넣는 정확한 `iss` 클레임입니다. 확실하지 않은 경우 샘플 토큰을 디코딩하세요: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' token`
JWKS source	대부분의 관리형 IdP의 경우 `discovery`입니다. discovery를 사용할 수 없는 경우에만 `explicit_url` 또는 `inline`을 선택하세요.
Discovery base / JWKS URL / Inline keys	모드별로 다릅니다. IdP가 발급자 URL에서 `.well-known`을 제공하는 경우 discovery에서는 비워 두세요.
CA cert PEM	IdP가 프라이빗 CA에서 TLS를 제공하는 경우에만 필요합니다. 대부분의 관리형 IdP는 공용 CA를 사용하므로 비워 두세요.

섹션	값
Basic info	이름과 선택적 설명입니다. 1단계에서 등록한 발급자를 선택하세요.
Match	subject 접두사, audience, 정확한 클레임 매칭의 경우 Static을 선택하고, 표현식의 경우 CEL을 선택하세요. IdP의 클레임이 허용하는 한 최대한 구체적으로 지정하세요. 너무 광범위하게 매치되는 규칙은 의도한 것보다 더 많은 액세스 권한을 부여합니다.
Target	2단계에서 생성한 서비스 계정을 선택하세요.
Authorization	OAuth 스코프(기본값은 `workspace:developer`, 또는 `org:manage_tunnels`와 같은 제품별 스코프. OAuth 스코프 참조) 및 토큰 수명(초)입니다.