Admin API로 WIF 관리하기
infrastructure-as-code 및 CI 워크플로를 위해 Workload Identity Federation 서비스 계정, 발급자, 규칙을 프로그래밍 방식으로 생성하고 관리합니다.
Admin API를 사용하면 Workload Identity Federation 리소스인 서비스 계정, 페더레이션 발급자, 페더레이션 규칙을 프로그래밍 방식으로 생성하고 관리할 수 있습니다. 이를 사용하여 Claude Console에서 일일이 클릭하는 대신 페더레이션 구성을 "infrastructure as code"(코드형 인프라)로 유지하고, CI에서 프로비저닝하며, 여러 조직에 걸쳐 재현할 수 있습니다. 이러한 엔드포인트는 나머지 Admin API와 /v1/organizations 경로 접두사를 공유합니다.
사전 요구 사항
이 페이지의 모든 요청은 org:admin 범위를 가진 OAuth bearer 토큰으로 인증합니다. 이 범위는 admin, owner 또는 primary owner 역할을 가진 조직 구성원에게만 부여되며, 조직 전체에 대한 액세스 권한을 부여합니다. 즉, 워크스페이스 바인딩은 무시됩니다. 토큰을 얻는 방법은 두 가지이며, 각각 다른 권한을 가집니다. 본인의 로그인으로 얻은 토큰은 사용자로서 동작하는 반면, 페더레이션 토큰은 서비스 계정으로서 동작하며 이 페이지의 모든 작업을 수행할 수는 없습니다.
대화형(터미널)
전용 프로필로 ant CLI에 로그인하면서 org:admin 범위를 요청한 다음(관리자 액세스 참조), bearer 토큰을 내보내세요. --profile admin으로 로그인하면 org:admin 자격 증명이 별도의 프로필 이름으로 저장되고 CLI의 활성 프로필로도 설정되며, 내보낸 변수는 해당 셸의 모든 SDK 및 CLI 호출에 적용됩니다. 따라서 관리 작업 전용 셸을 사용하고, 작업이 끝나면 변수를 해제한 뒤 ant profile activate default로 CLI를 다시 전환하세요:
ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_AUTH_TOKEN=$(ant auth print-credentials --profile admin --access-token)대화형 토큰은 수명이 짧습니다. 요청이 401을 반환하기 시작하면 export 명령을 다시 실행하세요(토큰이 자동으로 갱신됩니다).
SDK와 ant CLI는 ANTHROPIC_AUTH_TOKEN을 자동으로 읽습니다. 같은 셸에서 ANTHROPIC_API_KEY는 설정하지 않은 상태로 두세요. 이러한 엔드포인트는 API 키를 거부하며, 둘 다 설정된 경우 모든 클라이언트가 키를 사용하기 때문입니다.
워크로드(CI 및 자동화)
organization_role이 admin인 서비스 계정을 대상으로 하는 oauth_scope: org:admin 페더레이션 규칙을 생성하세요. 이 규칙 자체는 Claude Console에서 생성해야 합니다. 워크로드에 조직 관리자 액세스 권한을 부여하는 것은 사람이 의도적으로 수행해야 하는 작업이며, 자동화가 스스로 부트스트랩할 수 있는 것이 아닙니다. 다음 섹션에서는 조직당 한 번만 수행하는 이 설정 과정을 안내합니다.
WIF를 관리할 워크로드 부트스트랩하기
Console에서 생성한 규칙 하나만 있으면 나머지 페더레이션 구성을 infrastructure as code로 관리할 수 있습니다. 신뢰할 수 있는 단일 워크로드에 org:admin 범위를 부여하고, 해당 워크로드가 이 API를 통해 페더레이션 발급자와 모든 워크스페이스 범위 페더레이션 규칙을 관리하도록 하세요.
Console에서 org:admin 규칙 생성하기
Claude Console에서 Workload identity 페이지(
platform.claude.com/settings/workload-identity-federation)로 이동한 후 Connect workload를 선택하여 자동화 워크로드(예: 인프라 저장소의 GitHub Actions 워크플로)를 위한 페더레이션 규칙 하나를 생성하세요. Advanced rule options에서 규칙의 OAuth 범위를org:admin으로 설정하세요. 그러면 마법사가 Admin 조직 역할을 가진 새 서비스 계정을 생성합니다(또는 대상으로 사용할 기존 admin 서비스 계정을 선택하도록 요청합니다).워크로드의 ID 토큰 교환하기
SDK 중 하나 또는
antCLI를 사용하는 워크로드는 교환을 직접 수행하지 않습니다. SDK 클라이언트 생성하기의 추론 예시와 똑같이, 페더레이션 환경 변수로 클라이언트가 규칙을 가리키도록 하고 인수 없이 클라이언트를 생성하세요. 클라이언트는 첫 번째 요청 시 ID 토큰을 교환하고, 결과로 받은 액세스 토큰이 만료되기 전에 ID 토큰을 다시 읽어 재교환합니다:export ANTHROPIC_FEDERATION_RULE_ID=fdrl_... # the org:admin rule from step 1 export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000 export ANTHROPIC_SERVICE_ACCOUNT_ID=svac_... # the rule's target service account export ANTHROPIC_IDENTITY_TOKEN_FILE=/path/to/jwt # or ANTHROPIC_IDENTITY_TOKEN # ANTHROPIC_WORKSPACE_ID는 규칙이 모든 워크스페이스 또는 둘 이상의 # 워크스페이스에 활성화된 경우에만 필요합니다. org:admin 엔드포인트는 바인딩을 무시합니다. unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN # both take precedence over federationantCLI는 동일한 변수를 읽거나--federation-rule,--organization-id,--service-account-id,--identity-token-file플래그를 받습니다. 둘 이상의ant명령을 실행하는 워크로드의 경우 플래그나 환경 변수 대신 페더레이션 프로필을 사용하세요. 플래그나 변수를 사용하면 CLI가 모든 프로세스에서 ID 토큰을 다시 교환하는데,jti클레임을 포함하는 ID 토큰(GitHub Actions 토큰이 해당됨)은 한 번만 허용되므로 두 번째 명령은 거부됩니다. 또한 SDK와 달리 CLI는ANTHROPIC_WORKSPACE_ID나--workspace-id를 교환에 전달하지 않으므로, 규칙이 모든 워크스페이스 또는 둘 이상의 워크스페이스에 대해 활성화된 경우 교환에 사용할workspace_id를 CLI에 제공하는 유일한 방법은 프로필입니다. 모든 SDK는 동일한 설정을 명시적인 생성자 인수로도 받으며, 언어별 예시는 SDK 클라이언트 생성하기에 나와 있습니다. 전체 목록과 우선순위는 환경 변수 및 자격 증명 우선순위를 참조하세요.curl로 API를 호출하는 워크로드는 다른 페더레이션 워크로드와 동일한 토큰 교환을 사용하여 JWT를 수명이 짧은
org:adminbearer 토큰으로 직접 교환하고, 이를authorization: Bearer헤더에 담아 전송합니다.API를 통해 발급자 및 워크스페이스 범위 규칙 관리하기
클라이언트가 구성되면(curl의 경우 발급받은 토큰이
ANTHROPIC_AUTH_TOKEN에 있으면), 워크로드는 이 페이지의 엔드포인트를 사용하여 페더레이션 구성을 생성하고 관리합니다.
워크로드가 발급받은 토큰으로 수행할 수 있는 작업과 수행할 수 없는 작업은 권한 및 제약 조건을 참조하세요. Connect workload 마법사로 이미 발급자, 서비스 계정 또는 규칙을 생성한 경우, 다시 생성하는 대신 다음 엔드포인트로 목록을 조회하여 infrastructure-as-code 상태로 가져오세요.
인증
모든 엔드포인트는 https://api.anthropic.com/v1/organizations/ 아래에 있습니다. 페더레이션 및 서비스 계정 엔드포인트에 대한 모든 요청에는 API 버전 헤더와 bearer 토큰이 필요합니다:
SDK에서 이러한 엔드포인트는 client.organization.service_accounts, client.organization.federation.issuers, client.organization.federation.rules입니다(CLI에서는 ant organization:service-accounts, federation:issuers, federation:rules). SDK 및 CLI 예시는 기본 클라이언트를 생성하며, 이 클라이언트는 ANTHROPIC_AUTH_TOKEN의 bearer 토큰을 전송하거나, 자동화된 워크로드에서는 WIF를 관리할 워크로드 부트스트랩하기에 설명된 대로 페더레이션 교환을 직접 수행합니다. SDK 목록 메서드는 필요에 따라 추가 페이지를 가져오므로 limit은 페이지 크기를 설정합니다. PHP 및 Ruby 예시는 한 페이지만 읽습니다.
client = anthropic.Anthropic()
service_accounts = client.organization.service_accounts.list()
for service_account in service_accounts:
print(f"{service_account.id}: {service_account.name}")이러한 엔드포인트에서는 Admin API 키가 허용되지 않습니다. Admin API 페이지의 x-api-key 예시는 여기에 적용되지 않습니다.
서비스 계정
서비스 계정(svac_...)은 페더레이션 토큰이 대신하여 동작하는 비인간 ID입니다. organization_role을 developer로 설정하세요.
서비스 계정 생성:
client = anthropic.Anthropic()
service_account = client.organization.service_accounts.create(
name="inference-worker", organization_role="developer"
)
print(f"id: {service_account.id}")
print(f"name: {service_account.name}")서비스 계정 목록 조회:
client = anthropic.Anthropic()
service_accounts = client.organization.service_accounts.list(limit=20)
for service_account in service_accounts:
print(f"{service_account.id}: {service_account.name}")서비스 계정 보관:
client = anthropic.Anthropic()
service_account = client.organization.service_accounts.archive(
"svac_01ABCDEFabcdef0123456789XY"
)
print(f"id: {service_account.id}")
print(f"archived_at: {service_account.archived_at}")생성 엔드포인트는 새 서비스 계정을 반환합니다:
{
"id": "svac_...",
"name": "inference-worker",
"organization_role": "developer",
"created_at": "...",
"type": "service_account",
"...": "..."
}단일 서비스 계정을 읽거나 업데이트하려면 /v1/organizations/service_accounts/{service_account_id}에 GET 및 POST를 사용하세요. 페더레이션 토큰이 워크스페이스에서 동작하려면 먼저 서비스 계정이 해당 워크스페이스의 구성원이어야 합니다. 모든 서비스 계정은 조직의 기본 워크스페이스에 암묵적인 멤버십을 가집니다. 다른 워크스페이스에 대한 명시적 멤버십은 /v1/organizations/service_accounts/{service_account_id}/workspaces에 GET, POST, DELETE를 사용하여 추가하세요. 여기서 DELETE는 .../workspaces/{workspace_id}를 대상으로 합니다.
전체 매개변수 세부 정보와 응답 스키마는 서비스 계정 API 레퍼런스를 참조하세요.
페더레이션 발급자
페더레이션 발급자(fdis_...)는 OIDC ID 공급자를 조직에 등록합니다. jwks 필드는 Anthropic이 공급자의 서명 키를 가져오는 방식을 제어하는 구별된 유니온(discriminated union)입니다:
jwks 값 | 사용 시기 |
|---|---|
{"type": "discovery"} | 공급자가 발급자 URL에서 /.well-known/openid-configuration을 제공하는 경우. |
{"type": "explicit_url", "url": "..."} | JWKS 엔드포인트를 직접 가리키는 경우. |
{"type": "inline", "keys": [...]} | 공용 인터넷에서 접근할 수 없는 공급자의 키 세트를 업로드하는 경우. |
발급자를 등록합니다. 이 예시는 JWKS discovery를 사용하여 GitHub Actions를 등록합니다:
client = anthropic.Anthropic()
issuer = client.organization.federation.issuers.create(
name="github-actions",
issuer_url="https://token.actions.githubusercontent.com",
jwks={"type": "discovery"},
)
print(f"id: {issuer.id}")
print(f"name: {issuer.name}")
print(f"issuer_url: {issuer.issuer_url}")발급자 목록 조회:
client = anthropic.Anthropic()
issuers = client.organization.federation.issuers.list(limit=20)
for issuer in issuers:
print(f"{issuer.id}: {issuer.name}")발급자 보관:
client = anthropic.Anthropic()
issuer = client.organization.federation.issuers.archive(
"fdis_01ABCDEFabcdef0123456789XY"
)
print(f"id: {issuer.id}")
print(f"archived_at: {issuer.archived_at}")단일 발급자를 읽거나 업데이트하려면 /v1/organizations/federation_issuers/{issuer_id}에 GET 및 POST를 사용하세요. OAuth 호출자는 oauth_scope가 workspace:developer 또는 workspace:inference 이외의 값인 규칙을 뒷받침하는 발급자를 업데이트할 수 없습니다. 권한 및 제약 조건을 참조하세요.
전체 매개변수 세부 정보와 응답 스키마는 페더레이션 발급자 API 레퍼런스를 참조하세요.
페더레이션 규칙
페더레이션 규칙(fdrl_...)은 발급자를 서비스 계정에 바인딩합니다. 규칙의 일치 조건을 충족하는 발급자의 JWT는 규칙의 대상으로서 동작하는 토큰을 발급받을 수 있습니다. 생성 요청의 workspace_id는 생성 시 해당 워크스페이스에서 규칙을 활성화합니다. 이후 /federation_rules/{rule_id}/workspaces 하위 리소스를 통해 워크스페이스를 더 추가할 수 있습니다. 생성 시 workspace_id 또는 applies_to_all_workspaces: true 중 하나가 필요합니다.
규칙을 생성합니다. 이 예시는 main 브랜치에서 실행되는 GitHub Actions 배포가 서비스 계정으로서 동작하도록 허용합니다:
client = anthropic.Anthropic()
rule = client.organization.federation.rules.create(
name="gha-deploy",
issuer_id="fdis_01ABCDEFabcdef0123456789XY",
match={
"subject_prefix": "repo:my-org/my-repo:ref:refs/heads/main",
"claims": {"repository_owner": "my-org"},
},
target={
"type": "service_account",
"service_account_id": "svac_01ABCDEFabcdef0123456789XY",
},
workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
oauth_scope="workspace:developer",
token_lifetime_seconds=600,
)
print(f"id: {rule.id}")
print(f"name: {rule.name}")규칙 목록 조회(선택적으로 발급자별 필터링):
client = anthropic.Anthropic()
rules = client.organization.federation.rules.list(
issuer_id="fdis_01ABCDEFabcdef0123456789XY"
)
for rule in rules:
print(f"{rule.id}: {rule.name}")규칙 보관:
client = anthropic.Anthropic()
rule = client.organization.federation.rules.archive("fdrl_01ABCDEFabcdef0123456789XY")
print(f"id: {rule.id}")
print(f"archived_at: {rule.archived_at}")목록 엔드포인트는 규칙 한 페이지와 다음 페이지를 위한 커서를 반환합니다:
{
"data": [{ "id": "fdrl_...", "name": "gha-deploy", "...": "..." }],
"next_page": "..."
}단일 규칙을 읽거나 업데이트하려면 /v1/organizations/federation_rules/{rule_id}에 GET 및 POST를 사용하세요. 규칙이 토큰을 발급할 수 있는 워크스페이스를 관리하려면 /v1/organizations/federation_rules/{rule_id}/workspaces에 GET 및 POST를, /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}에 DELETE를 사용하세요.
전체 매개변수 세부 정보와 응답 스키마는 페더레이션 규칙 API 레퍼런스를 참조하세요.
권한 및 제약 조건
oauth_scope: org:admin을 가진 규칙은 organization_role이 admin인 서비스 계정을 대상으로 해야 합니다. 리소스 이름은 ^[a-z0-9-]+$와 일치해야 하고, 1~255자여야 하며, 각 리소스 유형별로 조직 내에서 고유해야 합니다. 전체 필드 수준 제약 조건은 유효성 검사 규칙을 참조하세요.
페이지네이션 및 보관
서비스 계정, 페더레이션 발급자, 페더레이션 규칙 목록 엔드포인트는 limit(1~100, 기본값 20)과 이전 응답에서 가져온 page 커서를 받습니다. 다음 요청에서 응답의 next_page 값을 page 쿼리 매개변수로 전달하세요. 규칙-워크스페이스 하위 리소스 목록은 페이지네이션 없이 전체 세트를 반환합니다. 보관된 리소스는 기본적으로 목록에서 숨겨집니다. 포함하려면 include_archived=true를 전달하세요.
보관은 소프트 삭제이며 멱등적입니다. 이미 보관된 리소스를 보관해도 성공합니다. 활성 페더레이션 규칙이 여전히 참조하고 있는 발급자나 서비스 계정을 보관하면 400이 반환됩니다. 먼저 규칙을 보관하세요.
참고 항목
- Workload Identity Federation: 개념 및 Console 설정 안내
- WIF 레퍼런스: 환경 변수, 유효성 검사 규칙, OAuth 범위 및 오류 코드
- Admin API: 나머지 조직 관리 기능
- Admin API 레퍼런스: 서비스 계정 및 페더레이션 엔드포인트에 대해 생성된 요청 및 응답 스키마
Was this page helpful?