Gestire WIF con l'Admin API

L'Admin API ti consente di creare e gestire in modo programmatico le risorse di Workload Identity Federation: account di servizio, issuer di federazione e regole di federazione. Usala per mantenere la tua configurazione di federazione come "infrastructure as code" (infrastruttura come codice), effettuarne il provisioning dalla CI e riprodurla tra organizzazioni invece di procedere manualmente nella Claude Console. Questi endpoint condividono il prefisso di percorso /v1/organizations con il resto dell'Admin API.

Prerequisiti

Ogni richiesta in questa pagina si autentica con un "bearer token" (token bearer) OAuth che include lo scope org:admin. Lo scope viene concesso solo ai membri dell'organizzazione con ruolo admin, owner o primary owner, e concede l'accesso all'intera organizzazione: qualsiasi associazione a un workspace viene ignorata. Esistono due modi per ottenere un token, e comportano permessi diversi: un token ottenuto dal tuo login agisce come un utente, mentre un token federato agisce come un account di servizio e non può eseguire tutte le operazioni descritte in questa pagina.

Interattivo (il tuo terminale)

Accedi con la CLI ant con un profilo dedicato, richiedendo lo scope org:admin (vedi Accesso admin), quindi esporta il token bearer. L'accesso con --profile admin memorizza la credenziale org:admin con il proprio nome di profilo e la rende anche il profilo attivo della CLI, e la variabile esportata si applica a ogni chiamata SDK e CLI in quella shell; quindi usa una shell riservata all'amministrazione, rimuovi la variabile quando hai finito e riporta la CLI al profilo predefinito con ant profile activate default:

ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_AUTH_TOKEN=$(ant auth print-credentials --profile admin --access-token)

I token interattivi hanno una durata breve; se le richieste iniziano a restituire 401, esegui di nuovo il comando di esportazione (aggiorna il token automaticamente).

Gli SDK e la CLI ant leggono ANTHROPIC_AUTH_TOKEN automaticamente; lascia ANTHROPIC_API_KEY non impostata nella stessa shell, perché questi endpoint rifiutano le chiavi API e ogni client usa la chiave quando entrambe sono impostate.

Workload (CI e automazione)

Crea una regola di federazione con oauth_scope: org:admin che abbia come destinazione un account di servizio il cui organization_role sia admin. La regola stessa deve essere creata nella Claude Console: concedere a un workload l'accesso di amministratore dell'organizzazione è un'azione umana deliberata, non qualcosa che l'automazione possa configurare da sola. La sezione successiva illustra questa configurazione da eseguire una sola volta per organizzazione.

Configurare un workload per gestire WIF

Una sola regola creata nella Console è sufficiente per portare il resto della tua configurazione di federazione sotto infrastructure as code: concedi a un singolo workload attendibile lo scope org:admin e lascia che quel workload gestisca gli issuer di federazione e ogni regola di federazione con ambito workspace tramite questa API.

1. 1

   Crea la regola org:admin nella Console

   Nella Claude Console, vai alla pagina Workload identity (platform.claude.com/settings/workload-identity-federation) e seleziona Connect workload per creare una regola di federazione per il tuo workload di automazione, ad esempio un workflow GitHub Actions nel tuo repository dell'infrastruttura. In Advanced rule options, imposta lo scope OAuth della regola su org:admin: la procedura guidata crea quindi il nuovo account di servizio con il ruolo di organizzazione Admin (oppure ti chiede di scegliere un account di servizio admin esistente come destinazione).

2. 2

   Scambia il token di identità del workload

   Un workload che usa uno degli SDK o la CLI ant non esegue lo scambio da solo. Indirizza il client alla regola con le variabili d'ambiente di federazione e costruiscilo senza argomenti, esattamente come per l'inferenza in Costruire il client SDK; il client scambia il token di identità alla prima richiesta e, prima che il token di accesso risultante scada, rilegge il token di identità e lo scambia di nuovo:

   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 è richiesto solo se la regola è abilitata per tutti
   # i workspace o per più di uno; gli endpoint org:admin ignorano il binding.
   unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN       # both take precedence over federation

   

   La CLI ant legge le stesse variabili, oppure accetta i flag --federation-rule, --organization-id, --service-account-id e --identity-token-file. Per un workload che esegue più di un comando ant, usa un profilo di federazione anziché flag o variabili d'ambiente: con flag o variabili la CLI scambia di nuovo il token di identità in ogni processo, e i token di identità che includono un claim jti (come i token di GitHub Actions) vengono accettati una sola volta, quindi un secondo comando verrebbe rifiutato; un profilo è anche l'unico modo per fornire alla CLI un workspace_id per lo scambio quando la regola è abilitata per tutti i workspace o per più di uno, perché a differenza degli SDK la CLI non passa ANTHROPIC_WORKSPACE_ID o --workspace-id nello scambio. Ogni SDK accetta anche le stesse impostazioni come argomenti espliciti del costruttore, mostrati per ciascun linguaggio in Costruire il client SDK. Vedi Variabili d'ambiente e Precedenza delle credenziali per l'elenco completo e l'ordine.

   Un workload che chiama l'API con curl scambia autonomamente il JWT con un token bearer org:admin di breve durata, usando lo stesso scambio di token di qualsiasi altro workload federato, e lo invia nell'header authorization: Bearer.

3. 3

   Gestisci issuer e regole con ambito workspace tramite l'API

   Con il client configurato (oppure, per curl, con il token generato in ANTHROPIC_AUTH_TOKEN), il workload crea e gestisce la tua configurazione di federazione usando gli endpoint descritti in questa pagina.

Per le operazioni che un token generato da un workload può e non può eseguire, vedi Permessi e vincoli. Se hai già creato issuer, account di servizio o regole con la procedura guidata Connect workload, elencali con gli endpoint seguenti e importali nello stato della tua infrastructure as code invece di ricrearli.

Autenticazione

Tutti gli endpoint si trovano sotto https://api.anthropic.com/v1/organizations/. Ogni richiesta agli endpoint di federazione e degli account di servizio richiede l'header della versione API e il token bearer:

Negli SDK questi endpoint sono client.organization.service_accounts, client.organization.federation.issuers e client.organization.federation.rules (ant organization:service-accounts, federation:issuers e federation:rules nella CLI). Gli esempi SDK e CLI costruiscono il client predefinito, che invia il token bearer da ANTHROPIC_AUTH_TOKEN oppure, in un workload automatizzato, esegue autonomamente lo scambio di federazione come descritto in Configurare un workload per gestire WIF. I metodi di elenco degli SDK recuperano ulteriori pagine su richiesta, quindi limit imposta la dimensione della pagina; gli esempi PHP e Ruby leggono una sola pagina.

client = anthropic.Anthropic()

service_accounts = client.organization.service_accounts.list()

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

Le chiavi Admin API non sono accettate su questi endpoint; gli esempi con x-api-key della pagina dell'Admin API non si applicano qui.

Account di servizio

Un account di servizio (svac_...) è l'identità non umana per conto della quale agisce un token federato. Imposta organization_role su developer.

Crea un account di servizio:

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}")

Elenca gli account di servizio:

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}")

Archivia un account di servizio:

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}")

L'endpoint di creazione restituisce il nuovo account di servizio:

{
  "id": "svac_...",
  "name": "inference-worker",
  "organization_role": "developer",
  "created_at": "...",
  "type": "service_account",
  "...": "..."
}

Per leggere o aggiornare un singolo account di servizio, usa GET e POST su /v1/organizations/service_accounts/{service_account_id}. Un account di servizio deve essere membro di un workspace prima che i token federati possano agire al suo interno. Ogni account di servizio ha un'appartenenza implicita al workspace predefinito della tua organizzazione; aggiungi appartenenze esplicite per altri workspace con GET, POST e DELETE su /v1/organizations/service_accounts/{service_account_id}/workspaces, dove DELETE ha come destinazione .../workspaces/{workspace_id}.

Per i dettagli completi sui parametri e gli schemi di risposta, consulta il riferimento API degli account di servizio.

Issuer di federazione

Un issuer di federazione (fdis_...) registra un provider di identità OIDC presso la tua organizzazione. Il campo jwks è un'unione discriminata che controlla il modo in cui Anthropic recupera le chiavi di firma del provider:

Registra un issuer. Questo esempio registra GitHub Actions con il discovery JWKS:

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}")

Elenca gli issuer:

client = anthropic.Anthropic()

issuers = client.organization.federation.issuers.list(limit=20)

for issuer in issuers:
    print(f"{issuer.id}: {issuer.name}")

Archivia un issuer:

client = anthropic.Anthropic()

issuer = client.organization.federation.issuers.archive(
    "fdis_01ABCDEFabcdef0123456789XY"
)

print(f"id: {issuer.id}")
print(f"archived_at: {issuer.archived_at}")

Per leggere o aggiornare un singolo issuer, usa GET e POST su /v1/organizations/federation_issuers/{issuer_id}. Un chiamante OAuth non può aggiornare un issuer che supporta una regola il cui oauth_scope sia diverso da workspace:developer o workspace:inference; vedi Permessi e vincoli.

Per i dettagli completi sui parametri e gli schemi di risposta, consulta il riferimento API degli issuer di federazione.

Regole di federazione

Una regola di federazione (fdrl_...) associa un issuer a un account di servizio: i JWT dell'issuer che soddisfano le condizioni di corrispondenza della regola possono generare token che agiscono per conto della destinazione della regola. Il workspace_id nella richiesta di creazione abilita la regola in quel workspace al momento della creazione; aggiungi altri workspace in seguito tramite la sotto-risorsa /federation_rules/{rule_id}/workspaces. In fase di creazione è obbligatorio specificare workspace_id oppure applies_to_all_workspaces: true.

Crea una regola. Questo esempio consente ai deploy di GitHub Actions dal branch main di agire come l'account di servizio:

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}")

Elenca le regole, facoltativamente filtrate per issuer:

client = anthropic.Anthropic()

rules = client.organization.federation.rules.list(
    issuer_id="fdis_01ABCDEFabcdef0123456789XY"
)

for rule in rules:
    print(f"{rule.id}: {rule.name}")

Archivia una regola:

client = anthropic.Anthropic()

rule = client.organization.federation.rules.archive("fdrl_01ABCDEFabcdef0123456789XY")

print(f"id: {rule.id}")
print(f"archived_at: {rule.archived_at}")

L'endpoint di elenco restituisce una pagina di regole e il cursore per la pagina successiva:

{
  "data": [{ "id": "fdrl_...", "name": "gha-deploy", "...": "..." }],
  "next_page": "..."
}

Per leggere o aggiornare una singola regola, usa GET e POST su /v1/organizations/federation_rules/{rule_id}. Per gestire i workspace in cui una regola può generare token, usa GET e POST su /v1/organizations/federation_rules/{rule_id}/workspaces e DELETE su /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.

Per i dettagli completi sui parametri e gli schemi di risposta, consulta il riferimento API delle regole di federazione.

Permessi e vincoli

Una regola con oauth_scope: org:admin deve avere come destinazione un account di servizio il cui organization_role sia admin. I nomi delle risorse devono corrispondere a ^[a-z0-9-]+$, avere una lunghezza compresa tra 1 e 255 caratteri ed essere univoci all'interno di un'organizzazione per ciascun tipo di risorsa; per i vincoli completi a livello di campo, vedi Regole di validazione.

Paginazione e archiviazione

Gli endpoint di elenco di account di servizio, issuer di federazione e regole di federazione accettano limit (da 1 a 100, valore predefinito 20) e un cursore page ricavato dalla risposta precedente. Passa il valore next_page della risposta come parametro di query page nella richiesta successiva. L'elenco della sotto-risorsa dei workspace delle regole restituisce l'insieme completo senza paginazione. Le risorse archiviate sono nascoste dagli elenchi per impostazione predefinita; passa include_archived=true per includerle.

L'archiviazione è un'eliminazione logica ed è idempotente: l'archiviazione di una risorsa già archiviata ha esito positivo. L'archiviazione di un issuer o di un account di servizio restituisce 400 finché una regola di federazione attiva vi fa ancora riferimento; archivia prima la regola.

Vedi anche

• Workload Identity Federation: concetti e procedura di configurazione nella Console
• Riferimento WIF: variabili d'ambiente, regole di validazione, scope OAuth e codici di errore
• Admin API: il resto delle funzionalità di gestione dell'organizzazione
• Riferimento Admin API: schemi di richiesta e risposta generati per gli endpoint degli account di servizio e di federazione