Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Questa pagina raccoglie le superfici di configurazione, i vincoli di validazione e le mappature degli errori per Workload Identity Federation. Per le procedure guidate di configurazione, consulta le guide dei provider.
POST /v1/oauth/token accetta un corpo JSON che utilizza il grant jwt-bearer di RFC 7523. Gli SDK costruiscono questa richiesta per te a partire dalle variabili d'ambiente; gli esempi cURL in ogni guida del provider mostrano il corpo grezzo.
| Campo | Obbligatorio | Descrizione |
|---|---|---|
grant_type | Sì | Sempre urn:ietf:params:oauth:grant-type:jwt-bearer. |
assertion | Sì | Il JWT OIDC emesso dal tuo identity provider. |
federation_rule_id | Sì | ID con tag (fdrl_...) della regola di federazione da valutare. |
organization_id | Sì | UUID della tua organizzazione Anthropic. |
service_account_id | Sì | ID con tag (svac_...) del service account di destinazione. |
workspace_id | Condizionale | ID con tag (wrkspc_...) del workspace a cui limitare l'ambito del token emesso, oppure il valore letterale default per il workspace predefinito dell'organizzazione. Obbligatorio quando la regola è abilitata per più di un workspace. Se omesso, il server seleziona l'unico workspace abilitato della regola. |
POST /v1/oauth/token restituisce una risposta token OAuth 2.0 standard (RFC 6749 §5.1):
| Campo | Tipo | Descrizione |
|---|---|---|
access_token | string | Il token Anthropic a breve durata, con prefisso sk-ant-oat01-.... Passalo come Authorization: Bearer <token>. |
token_type | string | Sempre Bearer. |
expires_in | integer | Secondi fino alla scadenza del token. |
scope | string | Lo scope OAuth concesso dalla regola corrispondente. |
L'SDK legge queste variabili per eseguire uno scambio di token federato senza argomenti del costruttore.
| Variabile | Obbligatoria | Descrizione | Esempio |
|---|---|---|---|
ANTHROPIC_FEDERATION_RULE_ID | Sì | ID con tag della regola di federazione da valutare. | fdrl_... |
ANTHROPIC_ORGANIZATION_ID | Sì | UUID della tua organizzazione Anthropic. Lo trovi nella Claude Console sotto Settings > Organization. | 00000000-0000-0000-0000-000000000000 |
ANTHROPIC_IDENTITY_TOKEN_FILE | Una tra _TOKEN_FILE o _TOKEN | Percorso nel filesystem del JWT emesso dal tuo "identity provider" (provider di identità), o IdP. L'SDK rilegge questo file a ogni scambio in modo che i token proiettati che ruotano su disco siano sempre aggiornati. | /var/run/secrets/anthropic.com/token |
ANTHROPIC_IDENTITY_TOKEN | Una tra _TOKEN_FILE o _TOKEN | Il JWT letterale come stringa. Usala quando la tua piattaforma inietta il token come variabile d'ambiente anziché come file. | eyJhbGciOiJSUzI1NiIs... |
ANTHROPIC_SERVICE_ACCOUNT_ID | Sì | ID con tag del service account Anthropic di destinazione per conto del quale agisce il token di accesso emesso. | svac_... |
ANTHROPIC_WORKSPACE_ID | Condizionale | ID con tag del workspace a cui limitare l'ambito del token emesso, oppure il valore letterale default. Obbligatoria quando la regola di federazione è abilitata per più di un workspace; facoltativa quando la regola è associata a un singolo workspace. Il token emesso è limitato a questo workspace al momento dello scambio, quindi cambiare workspace richiede un nuovo scambio. | wrkspc_... |
ANTHROPIC_PROFILE | No | Nome di un profilo di configurazione da caricare. Ha la precedenza sulle variabili d'ambiente di federazione in questa tabella. | staging-profile |
Il percorso di federazione diretto tramite variabili d'ambiente si attiva solo quando ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e una tra ANTHROPIC_IDENTITY_TOKEN_FILE o ANTHROPIC_IDENTITY_TOKEN sono tutte impostate. ANTHROPIC_WORKSPACE_ID viene letta insieme alle altre ma non condiziona l'attivazione.
Una variabile impostata su una stringa vuota occupa comunque il suo posto nella catena di precedenza delle credenziali. Se viene esportato ANTHROPIC_API_KEY="", l'SDK seleziona il percorso della chiave API con una chiave vuota anziché passare alla federazione. Rimuovi le variabili di credenziali inutilizzate invece di svuotarle.
L'SDK risolve le credenziali in questo ordine. La prima sorgente che produce una credenziale vince.
| Ordine | Sorgente | Note |
|---|---|---|
| 1 | Argomento del costruttore (api_key=, auth_token=, credentials=) | Ha sempre la precedenza su tutto il resto. |
| 2 | ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN | Oscura completamente la federazione. Rimuovi queste variabili quando migri dalle chiavi API. |
| 3 | ANTHROPIC_PROFILE | Carica <config_dir>/configs/<name>.json. Un profilo nominato mancante è un errore, non un passaggio alla sorgente successiva. |
| 4 | Variabili d'ambiente di federazione | ANTHROPIC_FEDERATION_RULE_ID + ANTHROPIC_ORGANIZATION_ID + ANTHROPIC_SERVICE_ACCOUNT_ID + ANTHROPIC_IDENTITY_TOKEN[_FILE]. |
| 5 | Profilo attivo | Risolto da <config_dir>/active_config, con fallback a un profilo denominato default. |
Quando viene caricato un profilo, le variabili d'ambiente riempiono i campi che il profilo omette ma non sovrascrivono mai i campi che il profilo imposta esplicitamente. Ad esempio, ANTHROPIC_WORKSPACE_ID riempie workspace_id solo quando il profilo attivo non lo imposta.
Un profilo è un file di configurazione con nome che sia l'SDK sia la CLI ant leggono. I profili ti consentono di distribuire i parametri di federazione con la tua immagine container o di passare da un ambiente all'altro senza modificare il codice.
L'SDK individua la directory di configurazione in questo ordine:
$ANTHROPIC_CONFIG_DIR~/.config/anthropic su Linux e macOS%APPDATA%\Anthropic su WindowsIl nome del profilo attivo viene risolto in questo ordine:
$ANTHROPIC_PROFILE<config_dir>/active_config (un file di una riga scritto da ant profile activate <name>)defaultClaude Code e il Claude Agent SDK rispettano questo stesso ordine di risoluzione, quindi un profilo di federazione configurato qui autentica anche quegli strumenti senza configurazione aggiuntiva.
| Percorso | Contenuto | Sensibilità |
|---|---|---|
<config_dir>/configs/<profile>.json | version, il blocco authentication, organization_id, workspace_id e base_url. | Non segreto. Sicuro da committare o includere in un'immagine. |
<config_dir>/credentials/<profile>.json | version, l'access_token memorizzato nella cache, expires_at e (per il login interattivo) refresh_token. | Segreto. Scritto dall'SDK con modalità 0600. |
Sia il file di configurazione sia il file delle credenziali contengono un campo stringa di primo livello version nel formato major.minor (attualmente "1.0"). L'SDK scrive questo campo automaticamente in modo che le versioni future possano rilevare e migrare i formati più vecchi; omettilo quando crei una configurazione a mano e l'SDK tratterà il file come la versione corrente.
{
"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"
}Se authentication.identity_token viene omesso, l'SDK ricorre a ANTHROPIC_IDENTITY_TOKEN_FILE o ANTHROPIC_IDENTITY_TOKEN dall'ambiente.
L'oauth_scope che imposti su una regola di federazione determina quali endpoint della Claude API il token di accesso emesso può chiamare.
| Scope | Concede l'accesso a |
|---|---|
workspace:developer | Tutti gli endpoint non amministrativi della Claude API nel workspace della regola: Messages (inclusi streaming e conteggio dei token), Models, Managed Agents e le loro sessioni, Files e Skills. Corrisponde all'accesso di una chiave API emessa per lo stesso workspace. |
workspace:inference | Gli endpoint di inferenza nel workspace della regola: Messages (inclusi streaming e conteggio dei token), Models e l'endpoint chat compatibile con OpenAI. Usalo per i carichi di lavoro che devono solo chiamare Claude e non hanno mai bisogno di gestire Files, Skills o altre risorse. |
workspace:manage_tunnels | L'API dei tunnel MCP: creare, elencare e ottenere tunnel, registrare e archiviare certificati CA, rivelare e ruotare il token del tunnel e archiviare tunnel. La finestra modale di creazione tunnel della Console blocca questo scope quando crei una regola da essa. |
org:admin | Accesso completo all'Admin API (membri dell'organizzazione, inviti, workspace, chiavi API e il resto). Un token OAuth org:admin può creare o modificare solo regole con scope workspace:developer o workspace:inference, e non può aggiornare un issuer che supporta una regola con qualsiasi altro scope; consulta i vincoli. |
Una richiesta a un endpoint al di fuori dello scope del token restituisce HTTP 403. Scope a granularità più fine (per risorsa, o lettura rispetto a scrittura) non sono attualmente disponibili.
L'oauth_scope di una regola di federazione è un tetto massimo: il token emesso non può mai superarlo. L'organization_role (developer o admin) del service account di destinazione determina quali scope sono concedibili, quindi una regola che concede org:admin deve avere come destinazione un service account con organization_role=admin. I permessi effettivi sono l'intersezione tra lo scope della regola e il ruolo del service account.
oauth_scope della regola | organization_role del service account | Permessi effettivi |
|---|---|---|
workspace:developer | admin | Accesso alla Claude API solo nel workspace della regola. Lo scope limita il token al di sotto del ruolo. |
org:admin | admin | Accesso completo all'Admin API (membri dell'organizzazione, inviti, workspace, chiavi API e il resto), meno le esclusioni per i chiamanti OAuth; consulta i vincoli. |
Anthropic applica questi vincoli quando crei o aggiorni issuer e regole, e quando verifica un JWT in ingresso al momento dello scambio.
Per i dettagli completi dei parametri e gli schemi di risposta, consulta il riferimento API dei service account, il riferimento API degli issuer di federazione e il riferimento API delle regole di federazione.
| Campo | Vincolo |
|---|---|
name di issuer, regola e service account | Deve corrispondere a ^[a-z0-9-]+$, lunghezza da 1 a 255 caratteri. |
workspace_id | Obbligatorio alla creazione a meno che applies_to_all_workspaces non sia true. Il workspace (wrkspc_...) le cui quote, fatturazione e limiti di velocità si applicano ai token emessi con questa regola. Deve essere un workspace nella stessa organizzazione, e il service account di destinazione deve essere membro di quel workspace. |
applies_to_all_workspaces | Booleano. Imposta true per abilitare la regola in ogni workspace dell'organizzazione invece di indicarne uno; alla creazione è obbligatorio questo campo oppure workspace_id. |
token_lifetime_seconds | Intero compreso tra 60 e 86400 (da 1 minuto a 24 ore). Predefinito 3600. I valori al di fuori di questo intervallo vengono rifiutati al momento della richiesta. Consulta Durata e aggiornamento del token. |
I campi issuer_url, jwks.discovery_base e jwks.url vengono validati:
| Vincolo | Dettaglio |
|---|---|
| Schema | Deve essere https. |
| Porta | Deve essere 443 (esplicita o predefinita). |
| Host | Deve essere un hostname DNS pubblico per il tuo provider OIDC. Deve risolversi in indirizzi IP pubblici; gli IP letterali non sono accettati. |
I fallimenti di validazione degli URL restituiscono 400 invalid_request_error con il nome del campo come prefisso del messaggio di errore (ad esempio, issuer_url: url must use https scheme).
I vincoli sugli URL si applicano solo agli URL che Anthropic contatta. Nelle modalità JWKS explicit_url e inline, e nella modalità discovery quando jwks.discovery_base è impostato, l'issuer_url viene confrontato con il claim iss del JWT come stringa e non viene mai recuperato, quindi può fare riferimento a un hostname interno o a una porta non standard.
| Vincolo | Dettaglio |
|---|---|
| Dimensione massima | Il JWT assertion deve essere al massimo di 16 KiB. |
| Algoritmo di firma | Sono accettati solo algoritmi asimmetrici (famiglie RSA ed ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512). HMAC (HS256, HS384, HS512) e none vengono rifiutati. |
| Key ID | L'header del JWT deve contenere un kid che corrisponda a una chiave nel JWKS dell'issuer. I token senza kid vengono rifiutati. |
| Claim obbligatori | sub deve essere presente. iat deve essere presente e non nel futuro. exp deve essere presente e nel futuro. |
| Durata massima | La durata del token (exp meno iat) non deve superare il massimo configurato per l'issuer (1 ora per impostazione predefinita, configurabile per ogni issuer nella Claude Console). |
| Scostamento dell'orologio | Viene applicata una tolleranza di 30 secondi a exp, nbf e iat. |
Il blocco match di una regola di federazione determina se un JWT in ingresso viene accettato. Tutti i campi popolati vengono valutati con semantica AND: il JWT deve soddisfare ogni matcher popolato. Almeno uno tra subject_prefix, claims o condition deve essere impostato; un blocco match che contiene solo audience (o nessun matcher) viene rifiutato. Questo protegge da regole che accetterebbero ogni token da un issuer.
| Matcher | Tipo | Semantica |
|---|---|---|
subject_prefix | string | Corrispondenza esatta con il claim sub del JWT. Un * finale lo rende una corrispondenza per prefisso (il valore di sub deve iniziare con i caratteri che precedono il *). Sensibile alle maiuscole. |
audience | string | Il claim aud del JWT deve contenere esattamente questa stringa. Quando aud è un array, qualsiasi elemento che corrisponde esattamente soddisfa il controllo. |
claims | map<string, string> | Ogni chiave è il nome di un claim di primo livello e ogni valore è il valore stringa esatto richiesto. Per claim annidati, numerici, booleani o complessi come liste e mappe, usa invece condition con un'espressione CEL. |
condition | string (CEL) | Un'espressione CEL che deve valutare a true. |
L'espressione condition ha accesso a una singola variabile:
| Variabile | Tipo | Contenuto |
|---|---|---|
claims | map | L'insieme completo dei claim JWT decodificati. Gli oggetti annidati sono accessibili come mappe annidate. |
Esempio:
claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]Le condizioni CEL sono confini di sicurezza. Un'espressione che valuta a true per più input del previsto concede un accesso più ampio del previsto. Preferisci i matcher statici quando esprimono il tuo vincolo.
POST /v1/oauth/token restituisce errori nel formato di errore API standard. L'SDK incapsula i fallimenti di scambio in un FederationExchangeError tipizzato (o equivalente nel linguaggio) che espone lo stato HTTP, il corpo della risposta e il request_id.
| Stato | Errore | Causa | Risoluzione |
|---|---|---|---|
| 400 | invalid_request | federation_rule_id è malformato o manca un campo obbligatorio della richiesta. | Verifica l'ID fdrl_ e che il corpo della richiesta includa tutti i campi obbligatori. |
| 400 | invalid_request | workspace_id_required: la regola di federazione è abilitata per più di un workspace e la richiesta omette workspace_id. | Imposta ANTHROPIC_WORKSPACE_ID (o il campo workspace_id del corpo in una richiesta grezza) sull'ID wrkspc_... a cui vuoi limitare l'ambito del token. Consulta Richiesta di scambio token. |
| 400 | invalid_grant | Il claim iss del JWT non è esattamente uguale all'issuer_url registrato. | Confronta byte per byte, inclusi gli slash finali e lo schema: jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson | .iss' <<< "$JWT". |
| 400 | invalid_grant | Il recupero del JWKS è fallito, il JWKS è obsoleto, oppure il JWT è stato firmato con una chiave non presente nel JWKS. | Per la modalità inline, aggiorna l'issuer con le chiavi ruotate. Per discovery ed explicit_url, conferma che l'endpoint JWKS sia raggiungibile sulla porta 443; se l'issuer ha recentemente ruotato la sua chiave di firma, consulta Rotazione delle chiavi e caching. |
| 400 | invalid_grant | Il claim exp del JWT è nel passato (oltre la finestra di tolleranza di 30 secondi). | Conferma che il tuo identity provider stia proiettando un token aggiornato e che l'SDK stia rileggendo il file del token. |
| 400 | invalid_grant | Il JWT è stato verificato ma i suoi claim non soddisfano il blocco match della regola. | Decodifica il JWT e confronta ogni claim con la regola. subject_prefix è sensibile alle maiuscole. audience richiede una corrispondenza esatta dell'elemento. |
| 400 | invalid_grant | Il federation_rule_id non esiste, è archiviato, oppure il JWT non è autorizzato per esso (consolidato per prevenire l'enumerazione). | Conferma l'ID della regola nella Claude Console e che la regola non sia stata archiviata. |
Tutti i fallimenti invalid_grant restituiscono HTTP 400; la causa specifica viene registrata solo lato server e non viene esposta nella risposta.
| Sintomo | Causa | Risoluzione |
|---|---|---|
| L'SDK segnala "no credentials" invece di effettuare lo scambio | Una tra ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID o ANTHROPIC_IDENTITY_TOKEN[_FILE] non è impostata e nessun profilo è attivo. | Imposta tutte e quattro le variabili, oppure configura un profilo. |
| L'SDK si autentica con una chiave API invece di federare | ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN è impostata e vince la precedenza. | Rimuovi la variabile della chiave o del token. |
FileNotFoundError alla prima richiesta | Il percorso in ANTHROPIC_IDENTITY_TOKEN_FILE non esiste. L'SDK apre il file in modo lazy al momento dello scambio. | Conferma che il volume del token proiettato sia montato e che il percorso corrisponda. |
| Lo scambio del token riesce ma una richiesta alla Claude API restituisce 403 | Lo scope del token emesso non concede l'accesso a quell'endpoint. | Verifica l'oauth_scope della regola rispetto agli scope OAuth. |
| L'autenticazione fallisce con una credenziale vuota | Una variabile d'ambiente di credenziale è esportata ma impostata su una stringa vuota. I valori vuoti vincono comunque il loro posto nella precedenza. | Rimuovi la variabile con unset VAR anziché VAR="". |
Una risposta 400 invalid_grant è intenzionalmente opaca; la causa specifica viene registrata solo lato server.
Inizia dalla pagina della cronologia di autenticazione nella Claude Console. I tentativi di scambio recenti mostrano l'issuer e la regola che sono stati valutati, i claim JWT che sono stati ispezionati e quale passaggio di validazione è fallito, il che di solito rende superflui i controlli seguenti.
Se hai ancora bisogno di eseguire il debug a partire dal JWT stesso, esegui questi controlli in ordine:
Decodifica il JWT
Decodifica l'assertion che hai inviato in modo da poter confrontare ogni claim con la configurazione del tuo issuer e della tua regola:
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"Verifica che iss corrisponda all'issuer
Il claim iss decodificato deve essere uguale all'issuer_url registrato byte per byte, inclusi schema, porta ed eventuale slash finale. Una discrepanza su un singolo carattere fa fallire la verifica.
Verifica che aud corrisponda alla regola
Il claim aud decodificato deve contenere il valore audience della regola come corrispondenza esatta. Quando aud è un array, un elemento deve corrispondere esattamente.
Verifica sub e ogni voce di claims
Confronta sub con il subject_prefix della regola (sensibile alle maiuscole; un * finale è una corrispondenza per prefisso, qualsiasi altra cosa è esatta). Confronta ogni chiave nella mappa claims della regola con il claim di primo livello con lo stesso nome.
Verifica exp, nbf e iat
exp deve essere nel futuro e nbf/iat devono essere nel passato, entro la finestra di tolleranza di 30 secondi. Se l'orologio dell'host del carico di lavoro è andato fuori sincronia, un token altrimenti valido viene rifiutato.
Verifica la raggiungibilità del JWKS
Per la modalità discovery, recupera <jwks.discovery_base or issuer_url>/.well-known/openid-configuration tramite HTTPS pubblico sulla porta 443 e conferma che jwks_uri si risolva. Per explicit_url, recupera direttamente l'URL del JWKS. Per inline, conferma che la chiave di firma dell'issuer non sia stata ruotata da quando hai registrato le chiavi.
Se l'issuer ha ruotato la sua chiave di firma e ha iniziato immediatamente a firmare con essa, gli scambi possono fallire per un massimo di un minuto mentre la cache JWKS di Anthropic si aggiorna. Consulta Rotazione delle chiavi e caching.
Quando registri un issuer di federazione, il campo jwks controlla come Anthropic ottiene le chiavi pubbliche utilizzate per verificare le firme JWT di quell'issuer. È una union discriminata basata su type:
jwks.type | Forma di jwks | Comportamento | Da usare quando |
|---|---|---|---|
discovery (predefinito) | { "type": "discovery", "discovery_base": "https://..." } (discovery_base è facoltativo; impostalo quando l'URL di discovery differisce da issuer_url) | Anthropic recupera <discovery_base or issuer_url>/.well-known/openid-configuration, legge jwks_uri dal documento di discovery e recupera il JWKS da lì. | Il tuo IdP serve un documento di discovery OIDC standard su internet pubblico. La maggior parte dei provider gestiti (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) lo supporta. |
explicit_url | { "type": "explicit_url", "url": "https://..." } | Anthropic recupera il JWKS direttamente da url. L'issuer_url viene usato solo per il confronto come stringa con il claim iss del JWT e non viene mai contattato. | Il tuo IdP non serve un documento di discovery, oppure la discovery è solo interna ma il JWKS è raggiungibile pubblicamente. |
inline | { "type": "inline", "keys": [...] } | Fornisci l'array di oggetti JWK inline (l'array keys del documento JWKS, non l'oggetto contenitore). Anthropic non effettua alcuna richiesta in uscita. L'issuer_url viene usato solo per il confronto con iss. | Ambienti air-gapped, cluster Kubernetes autogestiti con URL dell'issuer interni al cluster, oppure quando vuoi un controllo esplicito sulla rotazione delle chiavi. |
La union discriminata rende i campi associati mutuamente esclusivi per costruzione. Sia discovery sia explicit_url accettano anche una stringa facoltativa ca_cert_pem per gli issuer che servono TLS da una CA privata.
Nelle modalità discovery ed explicit_url, Anthropic memorizza nella cache il JWKS recuperato. Se il tuo identity provider pubblica una nuova chiave di firma e inizia immediatamente a firmare i token con essa, gli scambi che presentano quei token possono fallire con un errore di firma per un massimo di 1 minuto mentre la cache si aggiorna.
Per evitare questa finestra, pubblica una nuova chiave di firma nel JWKS almeno 15 minuti prima che il tuo identity provider inizi a firmare i token con essa, e mantieni la chiave sostituita nel JWKS finché i token che ha firmato non sono scaduti. I provider di identità gestiti in genere seguono questa disciplina autonomamente. Se gestisci il tuo issuer (un cluster Kubernetes autogestito, un provider di discovery OIDC SPIRE o un authorization server personalizzato Okta con una cadenza di rotazione configurata), conferma che la tua policy di rotazione pubblichi le nuove chiavi prima del primo utilizzo.
Nella modalità inline non c'è alcun aggiornamento automatico delle chiavi. Quando il tuo identity provider ruota le sue chiavi di firma, devi aggiornare la configurazione dell'issuer con il nuovo JWKS, altrimenti tutti gli scambi di token falliranno la verifica della firma.
Was this page helpful?