관리자인증

WIF 참조

Workload Identity Federation을 위한 환경 변수, 유효성 검사 규칙, 프로필 구성 및 오류 참조입니다.

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

토큰 교환 요청

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

필드	필수 여부	설명
`grant_type`	예	항상 `urn:ietf:params:oauth:grant-type:jwt-bearer`입니다.
`assertion`	예	ID 공급자가 발급한 OIDC JWT입니다.
`federation_rule_id`	예	평가할 페더레이션 규칙의 태그가 지정된 ID(`fdrl_...`)입니다.
`organization_id`	예	Anthropic 조직의 UUID입니다.
`service_account_id`	예	대상 서비스 계정의 태그가 지정된 ID(`svac_...`)입니다.
`workspace_id`	조건부	발급된 토큰의 범위를 지정할 워크스페이스의 태그가 지정된 ID(`wrkspc_...`) 또는 조직의 기본 워크스페이스를 나타내는 리터럴 `default`입니다. 규칙이 둘 이상의 워크스페이스에 대해 활성화된 경우 필수입니다. 생략하면 서버가 규칙의 유일한 활성화된 워크스페이스를 선택합니다.

토큰 교환 응답

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

필드	타입	설명
`access_token`	string	`sk-ant-oat01-...` 접두사가 붙은 단기 Anthropic 토큰입니다. `Authorization: Bearer <token>`으로 전달하세요.
`token_type`	string	항상 `Bearer`입니다.
`expires_in`	integer	토큰이 만료될 때까지의 시간(초)입니다.
`scope`	string	일치한 규칙이 부여한 OAuth 스코프입니다.

환경 변수

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

변수	필수 여부	설명	예시
`ANTHROPIC_FEDERATION_RULE_ID`	예	평가할 페더레이션 규칙의 태그가 지정된 ID입니다.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	예	Anthropic 조직의 UUID입니다. Claude Console의 Settings > Organization에서 확인할 수 있습니다.	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	`_TOKEN_FILE` 또는 `_TOKEN` 중 하나	ID 공급자(IdP)가 발급한 JWT의 파일 시스템 경로입니다. SDK는 디스크에서 순환되는 프로젝션된 토큰이 항상 최신 상태를 유지하도록 교환할 때마다 이 파일을 다시 읽습니다.	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	`_TOKEN_FILE` 또는 `_TOKEN` 중 하나	문자열 형태의 리터럴 JWT입니다. 플랫폼이 토큰을 파일이 아닌 환경 변수로 주입하는 경우 사용하세요.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	예	발급된 액세스 토큰이 대행할 대상 Anthropic 서비스 계정의 태그가 지정된 ID입니다.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	조건부	발급된 토큰의 범위를 지정할 워크스페이스의 태그가 지정된 ID 또는 리터럴 `default`입니다. 페더레이션 규칙이 둘 이상의 워크스페이스에 대해 활성화된 경우 필수이며, 규칙이 단일 워크스페이스에 바인딩된 경우 선택 사항입니다. 발급된 토큰은 교환 시점에 이 워크스페이스로 범위가 지정되므로 워크스페이스를 전환하려면 새로운 교환이 필요합니다.	`wrkspc_...`
`ANTHROPIC_PROFILE`	아니요	로드할 구성 프로필의 이름입니다. 이 표의 페더레이션 환경 변수보다 우선합니다.	`staging-profile`

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

빈 문자열로 설정된 변수도 자격 증명 우선순위 체인에서 해당 슬롯을 차지합니다. ANTHROPIC_API_KEY=""가 내보내진 경우, SDK는 페더레이션으로 넘어가지 않고 빈 키로 API 키 경로를 선택합니다. 사용하지 않는 자격 증명 변수는 빈 값으로 두지 말고 설정 해제하세요.

자격 증명 우선순위

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

순서	소스	참고
1	생성자 인수(`api_key=`, `auth_token=`, `credentials=`)	항상 다른 모든 것보다 우선합니다.
2	`ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`	페더레이션을 완전히 가립니다. API 키에서 마이그레이션할 때는 이 변수들을 설정 해제하세요.
3	`ANTHROPIC_PROFILE`	`<config_dir>/configs/<name>.json`을 로드합니다. 지정된 이름의 프로필이 없으면 다음 단계로 넘어가지 않고 오류가 발생합니다.
4	페더레이션 환경 변수	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`.
5	활성 프로필	`<config_dir>/active_config`에서 확인되며, 없으면 `default`라는 이름의 프로필로 대체됩니다.

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

프로필 구성 파일

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

구성 디렉터리

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

$ANTHROPIC_CONFIG_DIR
Linux 및 macOS에서는 ~/.config/anthropic
Windows에서는 %APPDATA%\Anthropic

활성 프로필

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

$ANTHROPIC_PROFILE
<config_dir>/active_config의 내용(ant profile activate <name>으로 작성된 한 줄짜리 파일)
리터럴 이름 default

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

파일 레이아웃

경로	내용	민감도
`<config_dir>/configs/<profile>.json`	`version`, `authentication` 블록, `organization_id`, `workspace_id`, `base_url`.	비밀 아님. 커밋하거나 이미지에 포함해도 안전합니다.
`<config_dir>/credentials/<profile>.json`	`version`, 캐시된 `access_token`, `expires_at`, (대화형 로그인의 경우) `refresh_token`.	비밀. SDK가 `0600` 모드로 작성합니다.

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

페더레이션 프로필 예시

configs/production.json

{
  "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 엔드포인트를 결정합니다.

스코프	접근 권한 부여 대상
`workspace:developer`	규칙의 워크스페이스에 있는 모든 비관리 Claude API 엔드포인트: Messages(스트리밍 및 토큰 카운팅 포함), Models, Managed Agents 및 해당 세션, Files, Skills. 이는 동일한 워크스페이스에 대해 발급된 API 키가 가진 접근 권한과 일치합니다.
`org:manage_tunnels`	MCP 터널 API: 터널 나열 및 조회, CA 인증서 등록 및 보관, 터널 토큰 공개 및 순환, 터널 보관. Console의 터널 생성 모달에서 규칙을 생성하면 이 스코프가 고정됩니다.

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

유효성 검사 규칙

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

리소스 필드

필드	제약 조건
발급자, 규칙, 서비스 계정 `name`	`^[a-z0-9-]+$`와 일치해야 하며, 길이는 1~255자입니다.
`workspace_id`	선택 사항. 이 규칙에 따라 발급된 토큰에 적용되는 할당량, 청구 및 속도 제한의 워크스페이스(`wrkspc_...`)입니다. 동일한 조직의 워크스페이스여야 하며, 대상 서비스 계정이 해당 워크스페이스의 구성원이어야 합니다. 하나의 워크스페이스에 대해서만 구성된 규칙의 경우 생략할 수 있습니다.
`token_lifetime_seconds`	`60`에서 `86400` 사이의 정수(1분~24시간). 기본값은 `3600`입니다. 이 범위를 벗어난 값은 요청 시점에 거부됩니다. 토큰 수명 및 갱신을 참조하세요.

URL 필드

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

제약 조건	세부 사항
스킴	`https`여야 합니다.
포트	`443`이어야 합니다(명시적 또는 기본값).
호스트	OIDC 공급자의 공개 DNS 호스트 이름이어야 합니다. 공개 IP 주소로 확인되어야 하며, IP 리터럴은 허용되지 않습니다.

URL 유효성 검사 실패는 필드 이름을 오류 메시지의 접두사로 하여 400 invalid_request_error를 반환합니다(예: issuer_url: url must use https scheme).

URL 제약 조건은 Anthropic이 연결하는 URL에만 적용됩니다. explicit_url 및 inline JWKS 모드에서, 그리고 jwks.discovery_base가 설정된 discovery 모드에서는 issuer_url이 JWT iss 클레임과 문자열로 비교되며 실제로 가져오지 않으므로 내부 호스트 이름이나 비표준 포트를 참조할 수 있습니다.

JWT 검증

제약 조건	세부 사항
최대 크기	`assertion` JWT는 최대 16 KiB여야 합니다.
서명 알고리즘	비대칭 알고리즘(RSA 및 ECDSA 계열: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512)만 허용됩니다. HMAC(`HS256`, `HS384`, `HS512`) 및 `none`은 거부됩니다.
키 ID	JWT 헤더는 발급자의 JWKS에 있는 키와 일치하는 `kid`를 포함해야 합니다. `kid`가 없는 토큰은 거부됩니다.
필수 클레임	`sub`가 있어야 합니다. `iat`가 있어야 하며 미래 시점이 아니어야 합니다. `exp`가 있어야 하며 미래 시점이어야 합니다.
최대 수명	토큰의 수명(`exp`에서 `iat`를 뺀 값)은 발급자에 구성된 최댓값(기본값 1시간, Claude Console에서 발급자별로 구성 가능)을 초과해서는 안 됩니다.
클록 스큐	`exp`, `nbf`, `iat`에 30초의 여유가 적용됩니다.

규칙 매칭 의미론

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

매처	타입	의미론
`subject_prefix`	string	JWT `sub` 클레임과 정확히 일치합니다. 끝에 ``가 있으면 접두사 일치가 됩니다(`sub` 값이 `` 앞의 문자로 시작해야 함). 대소문자를 구분합니다.
`audience`	string	JWT `aud` 클레임이 이 정확한 문자열을 포함해야 합니다. `aud`가 배열인 경우, 정확히 일치하는 요소가 하나라도 있으면 검사를 통과합니다.
`claims`	map<string, string>	각 키는 최상위 클레임 이름이고 각 값은 요구되는 정확한 문자열 값입니다. 중첩된 클레임, 숫자, 불리언, 또는 리스트와 맵 같은 복합 클레임의 경우 CEL 표현식과 함께 `condition`을 사용하세요.
`condition`	string (CEL)	`true`로 평가되어야 하는 CEL 표현식입니다.

CEL 평가 환경

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

변수	타입	내용
`claims`	map	디코딩된 전체 JWT 클레임 세트입니다. 중첩된 객체는 중첩된 맵으로 접근할 수 있습니다.

예시:

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

CEL 조건은 보안 경계입니다. 의도한 것보다 더 많은 입력에 대해 true로 평가되는 표현식은 의도한 것보다 더 넓은 접근 권한을 부여합니다. 제약 조건을 표현할 수 있는 경우 정적 매처를 우선적으로 사용하세요.

오류

토큰 교환 오류

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

상태	오류	원인	해결 방법
400	`invalid_request`	`federation_rule_id`의 형식이 잘못되었거나 필수 요청 필드가 누락되었습니다.	`fdrl_` ID를 확인하고 요청 본문에 모든 필수 필드가 포함되어 있는지 확인하세요.
400	`invalid_request`	`workspace_id_required`: 페더레이션 규칙이 둘 이상의 워크스페이스에 대해 활성화되어 있고 요청에서 `workspace_id`가 생략되었습니다.	토큰의 범위를 지정할 `wrkspc_...` ID로 `ANTHROPIC_WORKSPACE_ID`(또는 원시 요청의 `workspace_id` 본문 필드)를 설정하세요. 토큰 교환 요청을 참조하세요.
400	`invalid_grant`	JWT `iss` 클레임이 등록된 `issuer_url`과 정확히 일치하지 않습니다.	후행 슬래시와 스킴을 포함하여 바이트 단위로 비교하세요: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`.
400	`invalid_grant`	JWKS 가져오기 실패, JWKS가 오래됨, 또는 JWT가 JWKS에 없는 키로 서명되었습니다.	`inline` 모드의 경우 순환된 키로 발급자를 업데이트하세요. `discovery` 및 `explicit_url`의 경우 JWKS 엔드포인트가 포트 443에서 접근 가능한지 확인하세요. 발급자가 최근에 서명 키를 순환한 경우 키 순환 및 캐싱을 참조하세요.
400	`invalid_grant`	JWT `exp` 클레임이 과거입니다(30초 스큐 윈도우를 벗어남).	ID 공급자가 새 토큰을 프로젝션하고 있고 SDK가 토큰 파일을 다시 읽고 있는지 확인하세요.
400	`invalid_grant`	JWT가 검증되었지만 클레임이 규칙의 `match` 블록을 만족하지 않습니다.	JWT를 디코딩하고 각 클레임을 규칙과 비교하세요. `subject_prefix`는 대소문자를 구분합니다. `audience`는 정확한 요소 일치가 필요합니다.
400	`invalid_grant`	`federation_rule_id`가 존재하지 않거나, 보관되었거나, JWT가 해당 규칙에 대해 권한이 없습니다(열거 공격 방지를 위해 통합됨).	Claude Console에서 규칙 ID를 확인하고 규칙이 보관되지 않았는지 확인하세요.

모든 invalid_grant 실패는 HTTP 400을 반환합니다. 구체적인 원인은 서버 측에만 기록되며 응답에 노출되지 않습니다.

일반적인 SDK 측 실패

증상	원인	해결 방법
SDK가 교환 대신 "no credentials"를 보고함	`ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID`, `ANTHROPIC_IDENTITY_TOKEN[_FILE]` 중 하나가 설정되지 않았고 활성 프로필이 없습니다.	네 변수를 모두 설정하거나 프로필을 구성하세요.
SDK가 페더레이션 대신 API 키로 인증함	`ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`이 설정되어 우선순위를 차지합니다.	키 또는 토큰 변수를 설정 해제하세요.
첫 요청에서 `FileNotFoundError` 발생	`ANTHROPIC_IDENTITY_TOKEN_FILE`의 경로가 존재하지 않습니다. SDK는 교환 시점에 파일을 지연 로드합니다.	프로젝션된 토큰 볼륨이 마운트되어 있고 경로가 일치하는지 확인하세요.
토큰 교환은 성공하지만 Claude API 요청이 403을 반환함	발급된 토큰의 스코프가 해당 엔드포인트에 대한 접근 권한을 부여하지 않습니다.	규칙의 `oauth_scope`를 OAuth 스코프와 비교하여 확인하세요.
빈 자격 증명으로 인증 실패	자격 증명 환경 변수가 내보내졌지만 빈 문자열로 설정되어 있습니다. 빈 값도 우선순위 슬롯을 차지합니다.	`VAR=""` 대신 `unset VAR`로 변수를 설정 해제하세요.

실패한 교환 문제 해결

400 invalid_grant 응답은 의도적으로 불투명합니다. 구체적인 원인은 서버 측에만 기록됩니다.

Claude Console의 인증 기록 페이지부터 시작하세요. 최근 교환 시도는 평가된 발급자와 규칙, 검사된 JWT 클레임, 실패한 유효성 검사 단계를 보여주므로 일반적으로 다음 확인 단계를 건너뛸 수 있습니다.

JWT 자체에서 디버깅해야 하는 경우 다음 확인 사항을 순서대로 진행하세요.

JWT 디코딩
전송한 어설션을 디코딩하여 각 클레임을 발급자 및 규칙 구성과 비교할 수 있도록 하세요.
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
iss가 발급자와 일치하는지 확인
디코딩된 iss 클레임은 스킴, 포트, 후행 슬래시를 포함하여 등록된 issuer_url과 바이트 단위로 일치해야 합니다. 단 한 글자라도 불일치하면 검증이 실패합니다.
aud가 규칙과 일치하는지 확인
디코딩된 aud 클레임은 규칙의 audience 값을 정확히 일치하는 형태로 포함해야 합니다. aud가 배열인 경우 한 요소가 정확히 일치해야 합니다.
sub 및 각 claims 항목 확인
sub를 규칙의 subject_prefix와 비교하세요(대소문자 구분, 끝에 *가 있으면 접두사 일치, 그 외에는 정확한 일치). 규칙의 claims 맵에 있는 모든 키를 동일한 이름의 최상위 클레임과 비교하세요.
exp, nbf, iat 확인
exp는 미래여야 하고 nbf/iat는 30초 스큐 윈도우 내에서 과거여야 합니다. 워크로드 호스트의 시계가 어긋난 경우, 그 외에는 유효한 토큰도 거부됩니다.
JWKS 접근 가능성 확인
discovery 모드의 경우 포트 443의 공개 HTTPS를 통해 <jwks.discovery_base 또는 issuer_url>/.well-known/openid-configuration을 가져오고 jwks_uri가 확인되는지 검증하세요. explicit_url의 경우 JWKS URL을 직접 가져오세요. inline의 경우 키를 등록한 이후 발급자의 서명 키가 순환되지 않았는지 확인하세요.
발급자가 서명 키를 순환하고 즉시 해당 키로 서명을 시작한 경우, Anthropic의 JWKS 캐시가 새로 고쳐지는 동안 최대 1분간 교환이 실패할 수 있습니다. 키 순환 및 캐싱을 참조하세요.

JWKS 소스 모드

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

`jwks.type`	`jwks` 형태	동작	사용 시기
`discovery`(기본값)	`{ "type": "discovery", "discovery_base": "https://..." }`(`discovery_base`는 선택 사항이며, 디스커버리 URL이 `issuer_url`과 다른 경우 설정)	Anthropic이 `<discovery_base 또는 issuer_url>/.well-known/openid-configuration`을 가져오고, 디스커버리 문서에서 `jwks_uri`를 읽은 다음, 거기서 JWKS를 가져옵니다.	IdP가 공개 인터넷에서 표준 OIDC 디스커버리 문서를 제공하는 경우. 대부분의 관리형 공급자(EKS, GKE, Cloud Run, GitHub Actions, Entra ID)가 이를 지원합니다.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic이 `url`에서 직접 JWKS를 가져옵니다. `issuer_url`은 JWT `iss` 클레임과의 문자열 비교에만 사용되며 실제로 연결되지 않습니다.	IdP가 디스커버리 문서를 제공하지 않거나, 디스커버리는 내부 전용이지만 JWKS는 공개적으로 접근 가능한 경우.
`inline`	`{ "type": "inline", "keys": [...] }`	JWK 객체 배열을 인라인으로 제공합니다(래퍼 객체가 아닌 JWKS 문서의 `keys` 배열). Anthropic은 아웃바운드 요청을 하지 않습니다. `issuer_url`은 `iss` 비교에만 사용됩니다.	에어갭 환경, 클러스터 내부 발급자 URL을 사용하는 자체 관리형 Kubernetes 클러스터, 또는 키 순환을 명시적으로 제어하려는 경우.

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

키 순환 및 캐싱

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

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

inline 모드에서는 자동 키 새로 고침이 없습니다. ID 공급자가 서명 키를 순환하면 새 JWKS로 발급자 구성을 업데이트해야 하며, 그렇지 않으면 모든 토큰 교환이 서명 검증에 실패합니다.

Was this page helpful?

관리자인증

WIF 참조

Workload Identity Federation을 위한 환경 변수, 유효성 검사 규칙, 프로필 구성 및 오류 참조입니다.

토큰 교환 요청

필드	필수 여부	설명
`grant_type`	예	항상 `urn:ietf:params:oauth:grant-type:jwt-bearer`입니다.
`assertion`	예	ID 공급자가 발급한 OIDC JWT입니다.
`federation_rule_id`	예	평가할 페더레이션 규칙의 태그가 지정된 ID(`fdrl_...`)입니다.
`organization_id`	예	Anthropic 조직의 UUID입니다.
`service_account_id`	예	대상 서비스 계정의 태그가 지정된 ID(`svac_...`)입니다.
`workspace_id`	조건부	발급된 토큰의 범위를 지정할 워크스페이스의 태그가 지정된 ID(`wrkspc_...`) 또는 조직의 기본 워크스페이스를 나타내는 리터럴 `default`입니다. 규칙이 둘 이상의 워크스페이스에 대해 활성화된 경우 필수입니다. 생략하면 서버가 규칙의 유일한 활성화된 워크스페이스를 선택합니다.

토큰 교환 응답

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

필드	타입	설명
`access_token`	string	`sk-ant-oat01-...` 접두사가 붙은 단기 Anthropic 토큰입니다. `Authorization: Bearer <token>`으로 전달하세요.
`token_type`	string	항상 `Bearer`입니다.
`expires_in`	integer	토큰이 만료될 때까지의 시간(초)입니다.
`scope`	string	일치한 규칙이 부여한 OAuth 스코프입니다.

환경 변수

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

변수	필수 여부	설명	예시
`ANTHROPIC_FEDERATION_RULE_ID`	예	평가할 페더레이션 규칙의 태그가 지정된 ID입니다.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	예	Anthropic 조직의 UUID입니다. Claude Console의 Settings > Organization에서 확인할 수 있습니다.	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	`_TOKEN_FILE` 또는 `_TOKEN` 중 하나	ID 공급자(IdP)가 발급한 JWT의 파일 시스템 경로입니다. SDK는 디스크에서 순환되는 프로젝션된 토큰이 항상 최신 상태를 유지하도록 교환할 때마다 이 파일을 다시 읽습니다.	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	`_TOKEN_FILE` 또는 `_TOKEN` 중 하나	문자열 형태의 리터럴 JWT입니다. 플랫폼이 토큰을 파일이 아닌 환경 변수로 주입하는 경우 사용하세요.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	예	발급된 액세스 토큰이 대행할 대상 Anthropic 서비스 계정의 태그가 지정된 ID입니다.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	조건부	발급된 토큰의 범위를 지정할 워크스페이스의 태그가 지정된 ID 또는 리터럴 `default`입니다. 페더레이션 규칙이 둘 이상의 워크스페이스에 대해 활성화된 경우 필수이며, 규칙이 단일 워크스페이스에 바인딩된 경우 선택 사항입니다. 발급된 토큰은 교환 시점에 이 워크스페이스로 범위가 지정되므로 워크스페이스를 전환하려면 새로운 교환이 필요합니다.	`wrkspc_...`
`ANTHROPIC_PROFILE`	아니요	로드할 구성 프로필의 이름입니다. 이 표의 페더레이션 환경 변수보다 우선합니다.	`staging-profile`

자격 증명 우선순위

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

순서	소스	참고
1	생성자 인수(`api_key=`, `auth_token=`, `credentials=`)	항상 다른 모든 것보다 우선합니다.
2	`ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`	페더레이션을 완전히 가립니다. API 키에서 마이그레이션할 때는 이 변수들을 설정 해제하세요.
3	`ANTHROPIC_PROFILE`	`<config_dir>/configs/<name>.json`을 로드합니다. 지정된 이름의 프로필이 없으면 다음 단계로 넘어가지 않고 오류가 발생합니다.
4	페더레이션 환경 변수	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`.
5	활성 프로필	`<config_dir>/active_config`에서 확인되며, 없으면 `default`라는 이름의 프로필로 대체됩니다.

프로필 구성 파일

구성 디렉터리

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

$ANTHROPIC_CONFIG_DIR
Linux 및 macOS에서는 ~/.config/anthropic
Windows에서는 %APPDATA%\Anthropic

활성 프로필

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

$ANTHROPIC_PROFILE
<config_dir>/active_config의 내용(ant profile activate <name>으로 작성된 한 줄짜리 파일)
리터럴 이름 default

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

파일 레이아웃

경로	내용	민감도
`<config_dir>/configs/<profile>.json`	`version`, `authentication` 블록, `organization_id`, `workspace_id`, `base_url`.	비밀 아님. 커밋하거나 이미지에 포함해도 안전합니다.
`<config_dir>/credentials/<profile>.json`	`version`, 캐시된 `access_token`, `expires_at`, (대화형 로그인의 경우) `refresh_token`.	비밀. SDK가 `0600` 모드로 작성합니다.

페더레이션 프로필 예시

configs/production.json

{
  "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 엔드포인트를 결정합니다.

스코프	접근 권한 부여 대상
`workspace:developer`	규칙의 워크스페이스에 있는 모든 비관리 Claude API 엔드포인트: Messages(스트리밍 및 토큰 카운팅 포함), Models, Managed Agents 및 해당 세션, Files, Skills. 이는 동일한 워크스페이스에 대해 발급된 API 키가 가진 접근 권한과 일치합니다.
`org:manage_tunnels`	MCP 터널 API: 터널 나열 및 조회, CA 인증서 등록 및 보관, 터널 토큰 공개 및 순환, 터널 보관. Console의 터널 생성 모달에서 규칙을 생성하면 이 스코프가 고정됩니다.

유효성 검사 규칙

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

리소스 필드

필드	제약 조건
발급자, 규칙, 서비스 계정 `name`	`^[a-z0-9-]+$`와 일치해야 하며, 길이는 1~255자입니다.
`workspace_id`	선택 사항. 이 규칙에 따라 발급된 토큰에 적용되는 할당량, 청구 및 속도 제한의 워크스페이스(`wrkspc_...`)입니다. 동일한 조직의 워크스페이스여야 하며, 대상 서비스 계정이 해당 워크스페이스의 구성원이어야 합니다. 하나의 워크스페이스에 대해서만 구성된 규칙의 경우 생략할 수 있습니다.
`token_lifetime_seconds`	`60`에서 `86400` 사이의 정수(1분~24시간). 기본값은 `3600`입니다. 이 범위를 벗어난 값은 요청 시점에 거부됩니다. 토큰 수명 및 갱신을 참조하세요.

URL 필드

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

제약 조건	세부 사항
스킴	`https`여야 합니다.
포트	`443`이어야 합니다(명시적 또는 기본값).
호스트	OIDC 공급자의 공개 DNS 호스트 이름이어야 합니다. 공개 IP 주소로 확인되어야 하며, IP 리터럴은 허용되지 않습니다.

URL 유효성 검사 실패는 필드 이름을 오류 메시지의 접두사로 하여 400 invalid_request_error를 반환합니다(예: issuer_url: url must use https scheme).

JWT 검증

제약 조건	세부 사항
최대 크기	`assertion` JWT는 최대 16 KiB여야 합니다.
서명 알고리즘	비대칭 알고리즘(RSA 및 ECDSA 계열: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512)만 허용됩니다. HMAC(`HS256`, `HS384`, `HS512`) 및 `none`은 거부됩니다.
키 ID	JWT 헤더는 발급자의 JWKS에 있는 키와 일치하는 `kid`를 포함해야 합니다. `kid`가 없는 토큰은 거부됩니다.
필수 클레임	`sub`가 있어야 합니다. `iat`가 있어야 하며 미래 시점이 아니어야 합니다. `exp`가 있어야 하며 미래 시점이어야 합니다.
최대 수명	토큰의 수명(`exp`에서 `iat`를 뺀 값)은 발급자에 구성된 최댓값(기본값 1시간, Claude Console에서 발급자별로 구성 가능)을 초과해서는 안 됩니다.
클록 스큐	`exp`, `nbf`, `iat`에 30초의 여유가 적용됩니다.

규칙 매칭 의미론

매처	타입	의미론
`subject_prefix`	string	JWT `sub` 클레임과 정확히 일치합니다. 끝에 ``가 있으면 접두사 일치가 됩니다(`sub` 값이 `` 앞의 문자로 시작해야 함). 대소문자를 구분합니다.
`audience`	string	JWT `aud` 클레임이 이 정확한 문자열을 포함해야 합니다. `aud`가 배열인 경우, 정확히 일치하는 요소가 하나라도 있으면 검사를 통과합니다.
`claims`	map<string, string>	각 키는 최상위 클레임 이름이고 각 값은 요구되는 정확한 문자열 값입니다. 중첩된 클레임, 숫자, 불리언, 또는 리스트와 맵 같은 복합 클레임의 경우 CEL 표현식과 함께 `condition`을 사용하세요.
`condition`	string (CEL)	`true`로 평가되어야 하는 CEL 표현식입니다.

CEL 평가 환경

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

변수	타입	내용
`claims`	map	디코딩된 전체 JWT 클레임 세트입니다. 중첩된 객체는 중첩된 맵으로 접근할 수 있습니다.

예시:

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

오류

토큰 교환 오류

상태	오류	원인	해결 방법
400	`invalid_request`	`federation_rule_id`의 형식이 잘못되었거나 필수 요청 필드가 누락되었습니다.	`fdrl_` ID를 확인하고 요청 본문에 모든 필수 필드가 포함되어 있는지 확인하세요.
400	`invalid_request`	`workspace_id_required`: 페더레이션 규칙이 둘 이상의 워크스페이스에 대해 활성화되어 있고 요청에서 `workspace_id`가 생략되었습니다.	토큰의 범위를 지정할 `wrkspc_...` ID로 `ANTHROPIC_WORKSPACE_ID`(또는 원시 요청의 `workspace_id` 본문 필드)를 설정하세요. 토큰 교환 요청을 참조하세요.
400	`invalid_grant`	JWT `iss` 클레임이 등록된 `issuer_url`과 정확히 일치하지 않습니다.	후행 슬래시와 스킴을 포함하여 바이트 단위로 비교하세요: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`.
400	`invalid_grant`	JWKS 가져오기 실패, JWKS가 오래됨, 또는 JWT가 JWKS에 없는 키로 서명되었습니다.	`inline` 모드의 경우 순환된 키로 발급자를 업데이트하세요. `discovery` 및 `explicit_url`의 경우 JWKS 엔드포인트가 포트 443에서 접근 가능한지 확인하세요. 발급자가 최근에 서명 키를 순환한 경우 키 순환 및 캐싱을 참조하세요.
400	`invalid_grant`	JWT `exp` 클레임이 과거입니다(30초 스큐 윈도우를 벗어남).	ID 공급자가 새 토큰을 프로젝션하고 있고 SDK가 토큰 파일을 다시 읽고 있는지 확인하세요.
400	`invalid_grant`	JWT가 검증되었지만 클레임이 규칙의 `match` 블록을 만족하지 않습니다.	JWT를 디코딩하고 각 클레임을 규칙과 비교하세요. `subject_prefix`는 대소문자를 구분합니다. `audience`는 정확한 요소 일치가 필요합니다.
400	`invalid_grant`	`federation_rule_id`가 존재하지 않거나, 보관되었거나, JWT가 해당 규칙에 대해 권한이 없습니다(열거 공격 방지를 위해 통합됨).	Claude Console에서 규칙 ID를 확인하고 규칙이 보관되지 않았는지 확인하세요.

모든 invalid_grant 실패는 HTTP 400을 반환합니다. 구체적인 원인은 서버 측에만 기록되며 응답에 노출되지 않습니다.

일반적인 SDK 측 실패

증상	원인	해결 방법
SDK가 교환 대신 "no credentials"를 보고함	`ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID`, `ANTHROPIC_IDENTITY_TOKEN[_FILE]` 중 하나가 설정되지 않았고 활성 프로필이 없습니다.	네 변수를 모두 설정하거나 프로필을 구성하세요.
SDK가 페더레이션 대신 API 키로 인증함	`ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`이 설정되어 우선순위를 차지합니다.	키 또는 토큰 변수를 설정 해제하세요.
첫 요청에서 `FileNotFoundError` 발생	`ANTHROPIC_IDENTITY_TOKEN_FILE`의 경로가 존재하지 않습니다. SDK는 교환 시점에 파일을 지연 로드합니다.	프로젝션된 토큰 볼륨이 마운트되어 있고 경로가 일치하는지 확인하세요.
토큰 교환은 성공하지만 Claude API 요청이 403을 반환함	발급된 토큰의 스코프가 해당 엔드포인트에 대한 접근 권한을 부여하지 않습니다.	규칙의 `oauth_scope`를 OAuth 스코프와 비교하여 확인하세요.
빈 자격 증명으로 인증 실패	자격 증명 환경 변수가 내보내졌지만 빈 문자열로 설정되어 있습니다. 빈 값도 우선순위 슬롯을 차지합니다.	`VAR=""` 대신 `unset VAR`로 변수를 설정 해제하세요.

실패한 교환 문제 해결

400 invalid_grant 응답은 의도적으로 불투명합니다. 구체적인 원인은 서버 측에만 기록됩니다.

JWT 자체에서 디버깅해야 하는 경우 다음 확인 사항을 순서대로 진행하세요.

JWT 디코딩
전송한 어설션을 디코딩하여 각 클레임을 발급자 및 규칙 구성과 비교할 수 있도록 하세요.
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
iss가 발급자와 일치하는지 확인
디코딩된 iss 클레임은 스킴, 포트, 후행 슬래시를 포함하여 등록된 issuer_url과 바이트 단위로 일치해야 합니다. 단 한 글자라도 불일치하면 검증이 실패합니다.
aud가 규칙과 일치하는지 확인
디코딩된 aud 클레임은 규칙의 audience 값을 정확히 일치하는 형태로 포함해야 합니다. aud가 배열인 경우 한 요소가 정확히 일치해야 합니다.
sub 및 각 claims 항목 확인
sub를 규칙의 subject_prefix와 비교하세요(대소문자 구분, 끝에 *가 있으면 접두사 일치, 그 외에는 정확한 일치). 규칙의 claims 맵에 있는 모든 키를 동일한 이름의 최상위 클레임과 비교하세요.
exp, nbf, iat 확인
exp는 미래여야 하고 nbf/iat는 30초 스큐 윈도우 내에서 과거여야 합니다. 워크로드 호스트의 시계가 어긋난 경우, 그 외에는 유효한 토큰도 거부됩니다.
JWKS 접근 가능성 확인
discovery 모드의 경우 포트 443의 공개 HTTPS를 통해 <jwks.discovery_base 또는 issuer_url>/.well-known/openid-configuration을 가져오고 jwks_uri가 확인되는지 검증하세요. explicit_url의 경우 JWKS URL을 직접 가져오세요. inline의 경우 키를 등록한 이후 발급자의 서명 키가 순환되지 않았는지 확인하세요.
발급자가 서명 키를 순환하고 즉시 해당 키로 서명을 시작한 경우, Anthropic의 JWKS 캐시가 새로 고쳐지는 동안 최대 1분간 교환이 실패할 수 있습니다. 키 순환 및 캐싱을 참조하세요.

JWKS 소스 모드

`jwks.type`	`jwks` 형태	동작	사용 시기
`discovery`(기본값)	`{ "type": "discovery", "discovery_base": "https://..." }`(`discovery_base`는 선택 사항이며, 디스커버리 URL이 `issuer_url`과 다른 경우 설정)	Anthropic이 `<discovery_base 또는 issuer_url>/.well-known/openid-configuration`을 가져오고, 디스커버리 문서에서 `jwks_uri`를 읽은 다음, 거기서 JWKS를 가져옵니다.	IdP가 공개 인터넷에서 표준 OIDC 디스커버리 문서를 제공하는 경우. 대부분의 관리형 공급자(EKS, GKE, Cloud Run, GitHub Actions, Entra ID)가 이를 지원합니다.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic이 `url`에서 직접 JWKS를 가져옵니다. `issuer_url`은 JWT `iss` 클레임과의 문자열 비교에만 사용되며 실제로 연결되지 않습니다.	IdP가 디스커버리 문서를 제공하지 않거나, 디스커버리는 내부 전용이지만 JWKS는 공개적으로 접근 가능한 경우.
`inline`	`{ "type": "inline", "keys": [...] }`	JWK 객체 배열을 인라인으로 제공합니다(래퍼 객체가 아닌 JWKS 문서의 `keys` 배열). Anthropic은 아웃바운드 요청을 하지 않습니다. `issuer_url`은 `iss` 비교에만 사용됩니다.	에어갭 환경, 클러스터 내부 발급자 URL을 사용하는 자체 관리형 Kubernetes 클러스터, 또는 키 순환을 명시적으로 제어하려는 경우.

키 순환 및 캐싱

Was this page helpful?