WIF 참조

이 페이지는 Workload Identity Federation의 구성 인터페이스, 검증 제약 조건 및 오류 매핑을 모아 놓은 것입니다. 설정 안내는 공급자 가이드를 참조하세요.

토큰 교환 요청

POST /v1/oauth/token은 RFC 7523 jwt-bearer 그랜트를 사용하는 JSON 본문을 받습니다. SDK는 환경 변수로부터 이 요청을 자동으로 구성합니다. 각 공급자 가이드의 cURL 예제는 원시 본문을 보여 줍니다.

토큰 교환 응답

POST /v1/oauth/token은 표준 OAuth 2.0 토큰 응답(RFC 6749 §5.1)을 반환합니다:

환경 변수

SDK는 생성자 인수 없이 페더레이션 토큰 교환을 수행하기 위해 다음 변수를 읽습니다.

직접 환경 변수 페더레이션 경로는 ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, 그리고 ANTHROPIC_IDENTITY_TOKEN_FILE 또는 ANTHROPIC_IDENTITY_TOKEN 중 하나가 모두 설정된 경우에만 활성화됩니다. ANTHROPIC_WORKSPACE_ID는 함께 읽히지만 활성화 여부를 결정하지는 않습니다.

자격 증명 우선순위

SDK는 다음 순서로 자격 증명을 확인합니다. 자격 증명을 제공하는 첫 번째 소스가 선택됩니다.

프로필이 로드되면 환경 변수는 프로필이 생략한 필드를 채우지만, 프로필이 명시적으로 설정한 필드는 절대 덮어쓰지 않습니다. 예를 들어 ANTHROPIC_WORKSPACE_ID는 활성 프로필이 workspace_id를 설정하지 않은 경우에만 이를 채웁니다.

프로필 구성 파일

프로필은 SDK와 ant CLI가 모두 읽는 이름이 지정된 구성 파일입니다. 프로필을 사용하면 컨테이너 이미지와 함께 페더레이션 매개변수를 배포하거나 코드를 변경하지 않고 환경 간에 전환할 수 있습니다.

구성 디렉터리

SDK는 다음 순서로 구성 디렉터리를 찾습니다:

1. $ANTHROPIC_CONFIG_DIR
2. Linux 및 macOS의 경우 ~/.config/anthropic
3. Windows의 경우 %APPDATA%\Anthropic

활성 프로필

활성 프로필 이름은 다음 순서로 확인됩니다:

1. $ANTHROPIC_PROFILE
2. <config_dir>/active_config의 내용(ant profile activate <name>이 작성하는 한 줄짜리 파일)
3. 리터럴 이름 default

Claude Code와 Claude Agent SDK도 동일한 확인 순서를 따르므로, 여기에서 구성한 페더레이션 프로필은 추가 설정 없이 해당 도구들도 인증합니다.

파일 레이아웃

구성 파일과 자격 증명 파일 모두 major.minor 형식(현재 "1.0")의 최상위 문자열 version 필드를 가집니다. SDK는 향후 릴리스에서 이전 형식을 감지하고 마이그레이션할 수 있도록 이 필드를 자동으로 작성합니다. 구성을 직접 작성할 때 이 필드를 생략하면 SDK는 해당 파일을 현재 버전으로 취급합니다.

페더레이션 프로필 예시

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

authentication.identity_token이 생략되면 SDK는 환경의 ANTHROPIC_IDENTITY_TOKEN_FILE 또는 ANTHROPIC_IDENTITY_TOKEN으로 대체합니다.

OAuth 범위

페더레이션 규칙에 설정하는 oauth_scope는 발급된 액세스 토큰이 호출할 수 있는 Claude API 엔드포인트를 결정합니다.

토큰의 범위를 벗어난 엔드포인트에 대한 요청은 HTTP 403을 반환합니다. 더 세분화된 범위(리소스별 또는 읽기/쓰기 구분)는 현재 제공되지 않습니다.

권한 경계

페더레이션 규칙의 oauth_scope는 상한선입니다. 발급된 토큰은 이를 절대 초과할 수 없습니다. 대상 서비스 계정의 organization_role(developer 또는 admin)이 부여 가능한 범위를 결정하므로, org:admin을 부여하는 규칙은 organization_role=admin인 서비스 계정을 대상으로 해야 합니다. 유효 권한은 규칙의 범위와 서비스 계정 역할의 교집합입니다.

검증 규칙

Anthropic은 발급자와 규칙을 생성하거나 업데이트할 때, 그리고 교환 시점에 수신된 JWT를 검증할 때 다음 제약 조건을 적용합니다.

전체 매개변수 세부 정보와 응답 스키마는 서비스 계정 API 참조, 페더레이션 발급자 API 참조, 페더레이션 규칙 API 참조를 참조하세요.

리소스 필드

URL 필드

issuer_url, jwks.discovery_base, jwks.url 필드는 다음과 같이 검증됩니다:

URL 검증 실패는 오류 메시지 앞에 필드 이름이 접두사로 붙은 400 invalid_request_error를 반환합니다(예: issuer_url: url must use https scheme).

JWT 검증

규칙 매칭 의미론

페더레이션 규칙의 match 블록은 수신된 JWT의 수락 여부를 결정합니다. 채워진 모든 필드는 AND 의미론으로 평가됩니다. 즉, JWT는 채워진 모든 매처를 만족해야 합니다. subject_prefix, claims, condition 중 적어도 하나는 설정되어야 하며, audience만 포함하거나 매처가 전혀 없는 match 블록은 거부됩니다. 이는 발급자의 모든 토큰을 수락하는 규칙을 방지하기 위한 것입니다.

CEL 평가 환경

condition 표현식은 단일 변수에 접근할 수 있습니다:

예시:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

오류

토큰 교환 오류

POST /v1/oauth/token은 표준 API 오류 형식으로 오류를 반환합니다. SDK는 교환 실패를 HTTP 상태, 응답 본문 및 request_id를 노출하는 타입이 지정된 FederationExchangeError(또는 언어별 동등 항목)로 래핑합니다.

모든 assertion 거부는 어떤 검사가 실패했는지와 관계없이 고정 메시지 Authentication failed와 함께 동일한 불투명한 401 authentication_error를 반환합니다. 구별 가능한 오류는 호출자가 규칙 구성을 탐색할 수 있게 하기 때문입니다. 거부 사유는 인증 기록의 해당 시도 항목에 기록됩니다. 예를 들어 sub 클레임이 규칙의 subject_prefix를 통과하지 못하면 match_subject_prefix, 규칙이 여러 워크스페이스에 걸쳐 있고 요청이 아무것도 지정하지 않으면 workspace_id_required가 기록됩니다. 규칙의 조직이 확인되기 전에 거부된 요청(위의 400 invalid_request_error 계열)은 기록 항목을 남기지 않으며, 응답 메시지에 문제가 직접 명시됩니다. 일치하는 기록 항목이 없는 401은 일반적으로 federation_rule_id 자체가 인식되지 않았음을 의미합니다.

일반적인 SDK 측 실패

실패한 교환 문제 해결

401 authentication_error 응답은 의도적으로 불투명하며 메시지는 항상 Authentication failed입니다. 거부 사유는 응답이 아닌 인증 기록에 기록됩니다.

흔한 불투명 실패 중 하나는 재전송된 assertion입니다. jti 클레임이 있는 assertion은 한 번만 교환할 수 있으므로, 동일한 JWT를 다시 보내는 워크로드(재시도 루프 또는 교체되지 않은 토큰을 다시 읽는 갱신)는 두 번째 교환에서 거부됩니다. 인증 기록 페이지에는 이러한 시도가 사유 jti_reused와 함께 표시되며, 해결 방법은 매 교환마다 새로운 assertion을 발급하는 것입니다.

여전히 JWT 자체에서 디버깅해야 한다면 다음 검사를 순서대로 진행하세요:

1. 1

   JWT 디코딩

   각 클레임을 발급자 및 규칙 구성과 비교할 수 있도록 전송한 assertion을 디코딩하세요:

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   iss가 발급자와 일치하는지 확인

   디코딩된 iss 클레임은 스킴, 포트 및 끝의 슬래시를 포함하여 등록된 issuer_url과 바이트 단위로 일치해야 합니다. 단 한 글자라도 불일치하면 검증에 실패합니다.

3. 3

   aud가 규칙과 일치하는지 확인

   디코딩된 aud 클레임에는 규칙의 audience 값이 정확히 일치하는 형태로 포함되어야 합니다. aud가 배열인 경우 하나의 요소가 정확히 일치해야 합니다.

4. 4

   sub 및 각 claims 항목 확인

   sub를 규칙의 subject_prefix와 비교하세요(대소문자 구분, 끝의 *는 접두사 일치이며 그 외는 정확한 일치). 규칙의 claims 맵에 있는 모든 키를 같은 이름의 최상위 클레임과 비교하세요.

5. 5

   exp, nbf, iat 확인

   exp는 미래 시점이어야 하고 nbf/iat는 과거 시점이어야 하며, 30초 오차 허용 범위 내에 있어야 합니다. 워크로드 호스트의 시계가 어긋나 있으면 그 외에는 유효한 토큰도 거부됩니다.

6. 6

   JWKS 접근 가능성 확인

   discovery 모드의 경우 포트 443의 공개 HTTPS를 통해 <jwks.discovery_base or issuer_url>/.well-known/openid-configuration을 가져와 jwks_uri가 확인되는지 확인하세요. explicit_url의 경우 JWKS URL을 직접 가져오세요. inline의 경우 키를 등록한 이후 발급자의 서명 키가 교체되지 않았는지 확인하세요.

   발급자가 서명 키를 교체하고 즉시 해당 키로 서명을 시작한 경우, Anthropic의 JWKS 캐시가 갱신되는 동안 최대 1분간 교환이 실패할 수 있습니다. 키 교체 및 캐싱을 참조하세요.

JWKS 소스 모드

페더레이션 발급자를 등록할 때 jwks 필드는 Anthropic이 해당 발급자의 JWT 서명을 검증하는 데 사용하는 공개 키를 얻는 방법을 제어합니다. 이는 type을 키로 하는 구별된 유니온(discriminated union)입니다:

구별된 유니온은 구조적으로 동반 필드들을 상호 배타적으로 만듭니다. discovery와 explicit_url 모두 사설 CA로 TLS를 제공하는 발급자를 위해 선택적 ca_cert_pem 문자열도 허용합니다.

키 교체 및 캐싱

discovery 및 explicit_url 모드에서 Anthropic은 가져온 JWKS를 캐시합니다. ID 공급자가 새 서명 키를 게시하고 즉시 해당 키로 토큰 서명을 시작하면, 캐시가 갱신되는 동안 최대 1분간 해당 토큰을 제시하는 교환이 서명 오류로 실패할 수 있습니다.

이 기간을 피하려면 ID 공급자가 새 서명 키로 토큰 서명을 시작하기 최소 15분 전에 JWKS에 새 서명 키를 게시하고, 대체된 키로 서명된 토큰이 만료될 때까지 해당 키를 JWKS에 유지하세요. 관리형 ID 공급자는 일반적으로 자체적으로 이 원칙을 따릅니다. 자체 발급자(자체 관리형 Kubernetes 클러스터, SPIRE OIDC 디스커버리 공급자, 또는 교체 주기가 구성된 Okta 커스텀 인가 서버)를 운영하는 경우, 교체 정책이 최초 사용 전에 새 키를 게시하는지 확인하세요.