Distribuzione e operazioni del gateway delle app Claude

Registrare il gateway con il vostro IdP, costruire il container, distribuire su Kubernetes o Cloud Run, e gestirlo: controlli di integrità, rotazione dei segreti, aggiornamenti e sicurezza.

Questa pagina copre il lato operativo dell'esecuzione del gateway delle app Claude: registrazione di un client OAuth nel vostro provider di identità (IdP), distribuzione del gateway come container, e gestione quotidiana. Per ogni opzione nel file gateway.yaml che il gateway legge all'avvio, consultare il Riferimento di configurazione.

Una distribuzione in produzione segue quattro passaggi in ordine, e le sezioni sottostanti li corrispondono. I primi due sono dove fate scelte; i secondi due sono materiale di riferimento da consultare una volta che è in esecuzione.

1. Configurare il vostro provider di identità: registrare il client OAuth e controllare le note specifiche per IdP per Okta, Entra e Google
2. Distribuire il gateway: costruire un'immagine container con versione fissa ed eseguirla su Kubernetes, Cloud Run, o la vostra piattaforma. Questa sezione copre anche decisioni relative a costi, bypass, gateway multipli e serverless
3. Configurare le operazioni: log, sonde di integrità, comportamento in caso di interruzione, rotazione dei segreti e aggiornamenti. Riferimento per quando state collegando il monitoraggio e i runbook
4. Esaminare la postura di sicurezza: dove fluiscono i dati, il modello di minaccia e le risposte sulla conformità. Riferimento per una revisione della sicurezza

Se un accesso o un avvio fallisce lungo il percorso, andare direttamente a Troubleshooting, che è indicizzato in base all'errore che vedete.

Configurazione del provider di identità

Registra un'applicazione web OAuth/OpenID Connect (OIDC) confidenziale con un singolo URI di reindirizzamento, https://<gateway>/oauth/callback, e assegnala agli utenti o ai gruppi che dovrebbero avere accesso al gateway.

Qualsiasi IdP conforme a OIDC funziona: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate e altri. L'IdP deve soddisfare tre requisiti:

• Serve /.well-known/openid-configuration, su HTTPS in produzione; il gateway accetta un http:// issuer, e un issuer loopback richiede inoltre CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
• Supporta il flusso authorization-code. PKCE (Proof Key for Code Exchange) è attivo per impostazione predefinita; disabilitalo con oidc.use_pkce: false per IdP che non lo supportano
• Restituisce email e facoltativamente groups nell'id_token, o li serve dall'endpoint userinfo con oidc.userinfo_fallback: true

Per PKI privata, imposta oidc.ca_cert_pem.

Alcuni provider gestiscono i claim di email e gruppo diversamente:

• Okta: il server di autorizzazione dell'organizzazione in https://example.okta.com restituisce un id_token sottile che omette email e groups, quindi imposta oidc.userinfo_fallback: true ogni volta che lo usi come issuer. Un server di autorizzazione personalizzato come https://example.okta.com/oauth2/default che include email e facoltativamente groups nell'id_token li emette direttamente e non ha bisogno di fallback. Okta emette groups solo quando lo scope groups è richiesto in oidc.scopes e il filtro dei claim dei gruppi dell'app lo consente; userinfo_fallback non può riempire un claim per il quale l'IdP non è stato interrogato.
• Microsoft Entra ID: issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra emette Object ID dei gruppi piuttosto che nomi, quindi usa i GUID in managed.policies.match.groups, o usa App Roles per nomi leggibili. Se il tuo tenant emette ruoli sotto roles invece di groups, imposta oidc.groups_claim: roles.
• Google Workspace: issuer = https://accounts.google.com. L'id_token di Google non contiene gruppi. Per usare allowed_groups basato su gruppi o managed.policies con Google come IdP, configura oidc.google_groups, che cerca i gruppi di ogni utente tramite l'API Admin SDK Directory usando un account di servizio con delega a livello di dominio. Senza di esso, usa oidc.allowed_email_domains per il gating dell'appartenenza e managed.policies.match.email_domain per l'assegnazione della policy. Google ignora anche lo scope standard offline_access. Per i token di aggiornamento, imposta oidc.scopes: [openid, profile, email] e oidc.extra_auth_params: { access_type: offline, prompt: consent }.

Distribuzione

Il gateway è un singolo binario Linux senza stato che si coordina attraverso Postgres, quindi distribuiscilo come distribuisci qualsiasi altro servizio senza stato nel tuo ambiente. Mantienilo all'interno della tua rete, dove i tuoi sviluppatori e il tuo IdP possono raggiungerlo su HTTPS, e trattalo come qualsiasi servizio che contiene una credenziale di produzione.

Alcune decisioni modellano la distribuzione oltre a dove viene eseguito:

• Costo: nessuna licenza separata o tassa per posto. Il gateway fa parte del binario claude, quindi paghi per l'inferenza attraverso il tuo impegno esistente, più il calcolo su cui viene eseguito.
• Bypass: il gateway non applica che l'unica rotta a un modello passi attraverso di esso. Uno sviluppatore con la propria credenziale può comunque chiamare il provider direttamente, quindi chiudere quel percorso è una decisione di policy di rete, ad esempio bloccando l'uscita verso api.anthropic.com tranne dal gateway. Bloccare anche quell'uscita interrompe il controllo di sicurezza del dominio WebFetch, che chiama api.anthropic.com da ogni macchina dello sviluppatore. Imposta skipWebFetchPreflight: true nella policy gestita per disabilitarlo.
• Gateway multipli: ogni gateway è una distribuzione separata con la sua configurazione, e il CLI memorizza la fiducia e le credenziali per nome host del gateway, quindi i team possono utilizzare gateway diversi senza conflitto. Per servire più emittenti OIDC, esegui istanze separate.
• Serverless: Cloud Run funziona se imposti min-instances: 1 per evitare il cold start della scoperta OIDC. Lambda e Cloud Functions non funzionano, perché il gateway è un server HTTP a lunga durata.

Ogni topologia di produzione qui mette un proxy L7, come un Ingress, il front-end di Cloud Run, o un ALB, davanti alle repliche HTTP semplici. Imposta listen.trusted_proxies agli intervalli di origine del proxy in modo che il gateway legga gli IP client da X-Forwarded-For. Il gateway onora l'intestazione solo quando il peer TCP è affidabile. Gli esempi elaborati di Google Cloud e AWS hanno valori concreti per topologia. Senza proxy affidabili, ogni richiesta sembra provenire dall'IP del proxy, il che comprime i limiti di velocità per IP in un bucket condiviso e registra l'IP del proxy negli eventi di audit.

Non reindirizzare le richieste agli endpoint di autorizzazione del dispositivo e token del gateway, ad esempio con una riscrittura HTTP-to-HTTPS o di canonicalizzazione dell'host all'ingress. Claude Code non segue i reindirizzamenti su quelle richieste, quindi una regola di ingress che le reindirizza interrompe l'accesso e l'aggiornamento del token.

Dai al proxy un timeout di inattività più lungo dell'intervallo di keepalive del gateway, che dipende dall'upstream:

• Su ogni upstream tranne provider: anthropic, il gateway scrive un ping SSE una volta che un flusso è stato silenzioso per circa 15 secondi.
• Su provider: anthropic, il gateway passa la risposta invariata, inclusi i ping dell'API Anthropic.

Un valore predefinito come i 60 secondi dell'ALB è sufficiente per mantenere aperto un flusso silenzioso. L'esempio elaborato di AWS lo aumenta a un'ora comunque, e la sua riga di troubleshooting copre i gateway più vecchi di v2.1.229, che non hanno inviato nulla durante i periodi silenziosi sugli upstream che ora ricevono ping.

Immagine del container

Costruisci la tua immagine attorno al binario claude nativo dalla versione standard di Claude Code:

1. Scarica la build Linux per l'architettura della tua immagine da una versione fissa; consulta Installa una versione specifica per l'URL di download.
2. Verificalo rispetto al manifest.json firmato con GPG della versione come descritto in Integrità binaria e firma del codice.
3. Copialo nel contesto di build.

Specchia la versione nel tuo registro interno se le tue build non possono raggiungere l'host della versione, e fissa la versione che la tua flotta esegue.

Oltre al binario, l'immagine ha bisogno di:

• Un'immagine basata su glibc: la build glibc ha solo dipendenze dinamiche dalle librerie glibc. Le immagini basate su Musl hanno bisogno della build linux-x64-musl o linux-arm64-musl più pacchetti aggiuntivi; consulta Configurazione di Alpine Linux.
• Una directory di stato scrivibile: il gateway funziona come qualsiasi utente, ma le immagini minime non hanno home scrivibile. Imposta CLAUDE_CONFIG_DIR a un percorso scrivibile come /tmp/.claude.
• Il comando del container: claude gateway --config /etc/claude/gateway.yaml, con il file di configurazione montato in sola lettura e i segreti forniti come variabili di ambiente; il gateway ascolta su listen.port, predefinito 8080.

Kubernetes

Esegui il gateway come Deployment, come qualsiasi servizio senza stato:

• Monta la configurazione da una ConfigMap e i segreti da un Secret; fai riferimento ai segreti nel YAML tramite ${file:/path/to/secret} o come variabili di ambiente
• Termina TLS all'Ingress e imposta listen.public_url al nome host dell'Ingress
• Punta la sonda di readiness a GET /readyz e la sonda di liveness a GET /healthz

Per un esempio elaborato completo su AWS, che copre ECS Fargate o EKS, Amazon RDS e AWS Secrets Manager, consulta Distribuisci su AWS.

Preferisci l'identità del workload della piattaforma rispetto alle chiavi statiche; il riferimento upstreams ha dettagli di configurazione per piattaforma. Per un accoppiamento cross-cloud, come un upstream Bedrock su GKE, imposta credenziali esplicite nel blocco auth dell'upstream.

Cloud Run

Configura il servizio come segue:

• Lascia listen.port al suo predefinito di 8080, che corrisponde al PORT predefinito di Cloud Run, o imposta port: ${PORT}
• Imposta public_url all'origine esternamente raggiungibile. Per la produzione questo è normalmente il nome host di un load balancer interno, perché /login rifiuta gli indirizzi pubblici e l'URL *.run.app si risolve in uno, quindi l'URL di Cloud Run da solo funziona solo per un test di fumo curl o browser. L'eccezione è una rete dove *.run.app si risolve privatamente tramite Private Service Connect e una zona privata di Cloud DNS; in quella topologia l'URL di Cloud Run è un public_url valido. L'esempio elaborato di Google Cloud copre entrambi.
• Monta la configurazione come volume segreto
• Imposta min-instances: 1 per evitare il cold start della scoperta OIDC alla prima richiesta

Per un esempio elaborato completo su Google Cloud, che copre Cloud Run o GKE, Cloud SQL e Secret Manager, consulta Distribuisci su Google Cloud.

Invia l'URL del gateway alle macchine degli sviluppatori

Una volta che il gateway è in servizio, invia forceLoginMethod, forceLoginGatewayUrl e parentSettingsBehavior: "merge" a ogni macchina dello sviluppatore tramite impostazioni gestite, tramite MDM o scrivendo direttamente il managed-settings.json per OS. Senza questo, /login mostra il selettore di account standard senza opzione gateway.

Una volta che distribuisci le chiavi, Claude Code smette di utilizzare una chiave API rimasta o un accesso a claude.ai sulla macchina, quindi pianifica il push insieme alle tue istruzioni di accesso. La policy dell'amministratore richiede un accesso al gateway Cloud descrive i messaggi che gli sviluppatori vedono.

Consulta dove ogni meccanismo memorizza la policy per i percorsi dei file, e Impostazioni gestite lato client per l'equivalente bootstrapUrl di Claude Desktop.

Rollout su larga scala

L'accesso è limitato per indirizzo IP client, e i valori predefiniti si adattano a un piccolo team. Ogni indirizzo ottiene 30 avvii di accesso e 10 invii di codice ogni 10 minuti. Un rollout a migliaia di sviluppatori può raggiungere questi limiti la prima mattina, per uno di due motivi:

• Il gateway non può vedere oltre il tuo load balancer. Senza listen.trusted_proxies, ogni sviluppatore sembra provenire dall'indirizzo del load balancer e condivide un limite. Impostalo prima di qualsiasi altra cosa. Il gateway registra un avviso la prima volta che ignora un'intestazione X-Forwarded-For.
• Molti sviluppatori condividono pochi indirizzi di uscita NAT o VPN. Condividono i limiti di quegli indirizzi anche quando trusted_proxies è corretto. Aumenta rate_limits per adattarsi.

Per dimensionare max, dividi gli sviluppatori per gli indirizzi di uscita che condividono. Stima quanti di loro accedono entro un periodo window_seconds, che è 10 minuti per impostazione predefinita. Quindi raddoppialo per coprire i tentativi e gli sviluppatori che accedono sia a Claude Code che a Claude Desktop.

Ad esempio, 10.000 sviluppatori dietro 4 indirizzi di uscita accedono uniformemente in un'ora. Cioè 2.500 sviluppatori per indirizzo e circa 420 di loro in ogni 10 minuti, che raddoppi e arrotondi a 1.000. L'esempio seguente imposta entrambi i limiti a 1.000:

rate_limits:
  device_authorization: { max: 1000, window_seconds: 600 }
  device_verify: { max: 1000, window_seconds: 600 }

device_verify è quello che impedisce a qualcuno di indovinare il codice di accesso di un altro sviluppatore, quindi aumentalo solo quanto la tua stima ha bisogno. Anche a questi limiti, un codice è 8 caratteri da un alfabeto di 20 caratteri e scade dopo 10 minuti, quindi indovinare rimane impraticabile; consulta Resistenza al brute-force del codice utente.

Quando il tuo IdP emette token di aggiornamento, Claude Code rinnova le sessioni silenziosamente, quindi puoi rimettere il limite dopo il rollout. Senza token di aggiornamento, gli sviluppatori accedono di nuovo ogni session.ttl_hours. Dimensiona entrambi i limiti anche per quel tasso costante e lasciali aumentati.

Quando un limite viene raggiunto, Claude Code v2.1.274 o successivo mostra The gateway is limiting sign-in attempts right now. Un gateway su v2.1.274 o successivo mostra Too many attempts came from your network address sulla pagina di verifica, con le impostazioni da controllare. Scrive anche una riga di log sign-in refused che nomina l'impostazione da modificare.

Operazioni

Una volta che il gateway sta servendo il traffico, l'operazione quotidiana consiste nel leggere i suoi log, sondare la sua salute e ruotare i suoi segreti secondo il tuo programma. Le sottosezioni coprono ciascuno, più quello che Postgres contiene e come gli aggiornamenti e i rollback si comportano.

Log

Il gateway scrive due flussi su stderr, entrambi JSON-friendly:

• Eventi di audit: JSON a riga singola per evento rilevante per la sicurezza. Invia stderr al tuo aggregatore di log.

  Gli eventi emessi includono config.load, session.mint, session.refresh, device.authorize, device.verify, device.callback, auth.denied, access.denied, access.public_client, inference, managed.serve, desktop_bootstrap.serve, desktop_bootstrap.denied, spend.blocked, admin.denied, admin.limit.upsert, e admin.limit.delete. I campi variano per evento:

  • Gli eventi di mint e refresh riusciti portano sub, email, client_ip, e il risultato
  • auth.denied e access.denied portano il motivo e l'IP client, più il percorso della richiesta per auth.denied, poiché nessuna identità utente esiste in quelle negazioni. Due motivi di access.denied cambiano quello che l'evento porta:
    • xff_unparseable: l'evento porta anche la voce X-Forwarded-For che non poteva essere letta
    • client_ip_unknown: l'evento non porta alcun IP client, perché la connessione non aveva un indirizzo peer mentre era impostato un elenco access_control
  • access.public_client porta l'IP client della prima richiesta per processo che arriva da un indirizzo pubblico mentre access_control.allow_cidrs è vuoto. Il gateway serve la richiesta come al solito; l'evento segnala che il gateway potrebbe essere raggiungibile da internet pubblico. Vedi il riferimento access_control per quello che conta come pubblico e per l'elenco di autorizzazione consigliato.
  • inference registra quale upstream ha servito la richiesta e lo stato della risposta
  • desktop_bootstrap.denied registra un fetch di bootstrap di Claude Desktop rifiutato con il motivo (not_configured, policy_not_opted_in, o no_policy_matched) e l'identità dell'utente
  • admin.denied registra un tentativo di autenticazione dell'API admin rifiutato con l'IP client, il metodo, il percorso e un motivo, senza il materiale della chiave presentato: invalid_key quando è stato presentato un x-api-key ma non ha corrisposto a nessuna chiave configurata, bearer_rejected quando è stato presentato solo un header Authorization e non si è verificato come una sessione gateway in admin.admin_groups, o no_credentials quando nessun header è stato presentato

• Log operazionali: righe leggibili con prefisso [gateway] per avvio, avvertimenti e errori upstream. La variabile di ambiente CLAUDE_GATEWAY_LOG_LEVEL controlla la verbosità e accetta debug, info, warn, o error, con info come predefinito. A debug, ogni accesso e aggiornamento registra anche i nomi, non i valori, dei claim nell'id_token, più i nomi dei claim userinfo quando userinfo_fallback ha fornito qualcosa, così puoi diagnosticare le impostazioni email_claim e groups_claim senza registrare PII. Non influisce sugli eventi di audit, che sono sempre emessi.

Salute

Il gateway serve GET /healthz come sonda di liveness e GET /readyz come sonda di readiness; /readyz verifica che lo store sia raggiungibile. Entrambi sono esenti da access_control.allow_cidrs, quindi le sonde continuano a funzionare su un listener bloccato.

Il documento di scoperta OAuth in /.well-known/oauth-authorization-server restituisce anche 200 solo dopo il caricamento della configurazione, la scoperta OIDC, la costruzione del client upstream e la migrazione di Postgres, quindi funge anche da controllo di avvio end-to-end.

Richieste upstream concorrenti

Per impostazione predefinita, ogni replica del gateway invia al massimo 256 richieste upstream contemporaneamente. Una risposta in streaming conta rispetto al limite fino al termine dello stream.

Una richiesta che arriva mentre una replica è al limite attende all'interno del gateway per uno slot libero. Lo sviluppatore vede una risposta che è lenta a iniziare o sembra bloccarsi. Su un upstream provider: anthropic, una richiesta che attende più a lungo di timeouts.upstream_ttfb_ms rinuncia a quell'upstream e fallisce con un 502 quando nessun upstream successivo lo serve.

La riga di log di avvio che contiene upstream requests: mostra il limite in vigore. Mentre una replica ha più richieste aperte rispetto al limite, registra anche un avvertimento che contiene client requests are open, al massimo una volta al minuto.

Per servire più richieste contemporaneamente, hai due opzioni:

• Aggiungi repliche.
• Aumenta il limite su ogni replica. Imposta la variabile di ambiente BUN_CONFIG_MAX_HTTP_REQUESTS sul contenitore del gateway su un numero intero da 1 a 65535, quindi riavvia il contenitore.

Una replica riempie il suo limite a una velocità di richiesta di circa il limite diviso per il numero medio di secondi che una richiesta rimane aperta. Ad esempio, se le richieste rimangono aperte per 10 secondi in media, una replica al limite predefinito di 256 lo riempie a circa 26 richieste al secondo.

Se autoscali su CPU, una replica al limite mette in coda le richieste senza attivare uno scale-out, quindi imposta l'obiettivo al di sotto del livello di CPU che le tue repliche mostrano quando registrano l'avvertimento client requests are open.

Comportamento in caso di interruzione

Se Postgres si arresta, il gateway stesso continua a servire gli sviluppatori che hanno effettuato l'accesso e i nuovi accessi falliscono. Se gli sviluppatori effettivamente continuano a lavorare dipende da come il tuo orchestrator gestisce la readiness:

• Sessioni esistenti: i bearer token si convalidano localmente con il segreto JWT, gli aggiornamenti della sessione non toccano lo store, e il processo del gateway può comunque servire l'inferenza
• Nuovi accessi: falliscono fino al recupero di Postgres, perché il flusso del dispositivo e i suoi contatori di limite di velocità vivono in Postgres
• Applicazione del limite di spesa: fallisce aperto per impostazione predefinita durante l'interruzione, quindi l'inferenza continua a fluire; capovolgilo per fallire chiuso se preferisci bloccare piuttosto che eseguire senza misurazione
• Readiness: /readyz segnala non-ready durante l'interruzione, quindi gli orchestrator che controllano il traffico sulla readiness rimuovono ogni replica dalla rotazione contemporaneamente. In quella topologia tutto il traffico, inclusa l'inferenza che il gateway potrebbe comunque servire, fallisce al load balancer fino al recupero di Postgres. La sonda di liveness su /healthz continua a passare, quindi le repliche non vengono riavviate. Punta la sonda di readiness a /healthz invece se preferisci che gli sviluppatori che hanno effettuato l'accesso continuino a lavorare attraverso un'interruzione dello store; il costo è che i nuovi accessi falliscono contro una replica che ancora segnala ready.

Se il tuo IdP si arresta, le sessioni esistenti funzionano fino a ttl_hours, i nuovi accessi falliscono, e un aggiornamento della sessione riceve una risposta di riprovare e continua una volta che l'IdP è di nuovo disponibile. Imposta un ttl_hours più lungo se il tuo IdP ha frequenti finestre di manutenzione.

Rotazione del segreto JWT

Ruota il segreto di firma in tre passaggi in modo che le sessioni esistenti rimangono valide:

1. Genera un nuovo segreto. Anteponi l'array session.jwt_secret.
2. Esegui il rollout della distribuzione. I nuovi token firmano con il nuovo segreto; i vecchi token si convalidano comunque.
3. Dopo ttl_hours più un margine, rimuovi il vecchio segreto ed esegui di nuovo il rollout.

La rotazione è anche l'unico modo per forzare le sessioni prima che scadano: i bearer token si convalidano localmente rispetto al segreto JWT, quindi non c'è revoca per sessione. Sostituire il segreto completamente, senza mantenere il vecchio nell'array, invalida ogni sessione in sospeso contemporaneamente. Per l'offboarding individuale, esegui il deprovisioning dell'utente nel tuo IdP; la loro sessione termina entro ttl_hours.

Postgres

Il gateway contiene cinque tabelle di dati più una tabella _migrations, tutte create dalle sue migrazioni al momento dell'avvio:

Un ciclo di 30 secondi scade le righe kv oltre il loro TTL, e una pulizia oraria applica le finestre di conservazione sulle tabelle di spesa, quindi nulla cresce senza limiti. Senza limiti di spesa configurati, solo kv viene scritto. Il gateway applica le sue proprie migrazioni dello schema all'avvio e ad ogni aggiornamento, quindi il suo ruolo di database ha bisogno di diritti per creare e alterare le tabelle. Puntalo a un database o schema dedicato al gateway per mantenere quel grant stretto.

Con limiti di spesa in uso, un database perso significa perdita di tracciamento della spesa e limiti, non solo re-accessi degli sviluppatori, quindi esegui backup regolari. Per cancellare immediatamente uno sviluppatore partito piuttosto che aspettare la conservazione, esegui DELETE FROM principal_emails WHERE principal = '<sub>' direttamente; questo rimuove l'unica tabella che contiene la loro email, nome e gruppi. Le righe spend e admin_audit fanno riferimento solo allo pseudonimo OIDC sub.

Aggiornamenti

Le repliche sono senza stato, quindi un riavvio rolling non perde alcuno stato del gateway. Il gateway esegue migrazioni dello schema all'avvio, il che significa che distribuire il nuovo binario auto-migra il database. Le repliche concorrenti si serializzano su un lock consigliato di Postgres, quindi solo una applica ogni migrazione.

Quando il tuo orchestrator arresta una replica con SIGTERM, come in un riavvio rolling o uno scale-in, il gateway smette di accettare nuove connessioni e lascia che le richieste e gli stream già in volo finiscano prima di uscire. Attende fino a 25 secondi, chiamato la finestra di drenaggio, quindi chiude tutto ciò che è ancora aperto. Un SIGINT, come Ctrl+C in un terminale, avvia lo stesso drenaggio, e un secondo segnale durante il drenaggio chiude le richieste aperte ed esce subito. Il drenaggio richiede gateway v2.1.274 o successivo.

Le generazioni lunghe possono eseguire lo streaming per minuti. Su Kubernetes e Amazon ECS, aumenta entrambi questi insieme per dare a quegli stream più tempo:

• La finestra di drenaggio: imposta la variabile di ambiente CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS sul contenitore del gateway su un numero intero positivo di millisecondi, come 120000. Il gateway ignora un valore in qualsiasi altra forma, come 120s, e mantiene il predefinito di 25 secondi
• Il periodo di grazia del tuo orchestrator: terminationGracePeriodSeconds su Kubernetes, o stopTimeout su Amazon ECS

Il periodo di grazia predefinito è 30 secondi su entrambe le piattaforme. Mantienilo almeno 5 secondi più lungo della finestra di drenaggio, o l'orchestrator uccide il gateway prima che il drenaggio finisca. Su Kubernetes, aggiungi anche la durata di qualsiasi hook preStop, perché il periodo di grazia inizia a contare prima che l'hook venga eseguito piuttosto che quando il gateway riceve SIGTERM.

La tua piattaforma potrebbe anche limitare quanto a lungo il drenaggio può eseguire:

• Amazon ECS su Fargate: stopTimeout consente al massimo 120 secondi
• Cloud Run: arresta un'istanza 10 secondi dopo SIGTERM, quindi gli stream aperti ottengono al massimo 10 secondi lì, qualunque sia la finestra di drenaggio

Quando la finestra di drenaggio termina con richieste ancora aperte, il gateway registra un avvertimento che contiene drain window over after, conta le richieste che ha tagliato e nomina entrambe le impostazioni da aumentare.

Le migrazioni sono append-only, quindi il rollback a un binario precedente che conosce meno migrazioni è sicuro; ignora le righe extra. Il rollback ri-convalida anche il YAML rispetto allo schema del binario più vecchio, quindi una configurazione che ha adottato una chiave introdotta dalla versione più recente fallisce l'avvio su quella più vecchia. Rimuovi la nuova chiave prima di eseguire il rollback.

Poiché fissi la versione del gateway nella tua immagine, le correzioni nelle nuove versioni di Claude Code, incluse le correzioni di sicurezza, raggiungono la tua distribuzione solo quando aggiorni il pin e ridistribuisci. Includi il gateway nello stesso ciclo di patching che usi per altri servizi che contengono credenziali di produzione.

Sicurezza

Questa sezione risponde alle domande che una revisione di sicurezza pone: quali dati fluiscono attraverso il gateway e dove vanno, quali attacchi il design difende, e quali risposte appartengono a un questionario di conformità.

Flusso di dati

Riepilogo del modello di minaccia

Il gateway si trova all'interno del perimetro della tua rete, ma i singoli laptop degli sviluppatori non sono considerati affidabili. Il design tiene conto di questo in tre modi:

• Gli sviluppatori detengono JWT di breve durata invece di chiavi upstream grezze. La gamba CLI-to-gateway utilizza la concessione del dispositivo RFC 8628, e lo scambio di autorizzazione del gateway con l'IdP esegue PKCE nella configurazione predefinita, quindi un codice di autorizzazione IdP intercettato è inutile.

• La pagina di verifica del dispositivo applica POST della stessa origine e un limite di velocità per IP per RFC 8628 §5.1. Consulta Resistenza al brute-force del codice utente.

• Le richieste del gateway al tuo IdP, ai tuoi collettori OTLP e agli upstream provider: anthropic passano attraverso una guardia SSRF (Server-Side Request Forgery) che risolve DNS, blocca gli indirizzi link-local e cloud-metadata più loopback per impostazione predefinita, e fissa la connessione all'IP risolto, quindi gli URL influenzati dall'operatore non possono essere reindirizzati agli endpoint dei metadati cloud. Gli intervalli privati RFC 1918 sono deliberatamente consentiti, perché gli IdP e i collettori OTLP comunemente vivono su IP privati. Per gli altri provider, il gateway rifiuta un base_url che nomina uno di quegli indirizzi o un nome host di metadati quando carica la configurazione, e l'SDK del provider si connette quindi senza il controllo DNS.

  Se attivi egress solo proxy, quel controllo di indirizzo si sposta al tuo proxy in avanti: il gateway consegna i nomi host e la lista di consentiti del proxy deve rifiutare quelle destinazioni.

  Imposta CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 nell'ambiente del gateway solo quando qualcosa che il gateway deve raggiungere legittimamente vive su loopback, come un IdP di sviluppo locale o un collettore OTLP sidecar su localhost. La variabile rilassa il blocco loopback per ogni URL configurato dall'operatore e salta anche l'avviso al momento dell'avvio che controlla se il pod può raggiungere l'endpoint dei metadati cloud, quindi preferisci dare al collettore il suo indirizzo interno.

Se aggiungi i tuoi controlli di uscita, il gateway deve raggiungere il server dei metadati ogni volta che utilizza credenziali di metadati dell'istanza come workload identity.

Due minacce sono fuori ambito perché sono la tua infrastruttura da proteggere:

• Un host gateway compromesso: l'host sia contiene la credenziale upstream che distribuisce impostazioni gestite a ogni sviluppatore connesso, quindi il controllo sulla configurazione del gateway è paragonabile al controllo sul tuo MDM. La finestra di dialogo di approvazione del CLI per le impostazioni in grado di shell limita i cambiamenti silenziosi ma non sostituisce la sicurezza dell'host.
• Un provider OIDC malintenzionato: il provider firma gli id_token che il gateway si fida, quindi può asserire qualsiasi identità. Il vetting e la protezione del tuo IdP è tua responsabilità.

Resistenza al brute-force del codice utente

Il user_code che uno sviluppatore digita nella pagina di verifica /device è di 8 caratteri tratti da un alfabeto di 20 caratteri, che produce 20⁸ o circa 2,56×10¹⁰ combinazioni, e scade dopo 10 minuti.

Il gateway applica limiti di velocità per IP sugli endpoint di concessione del dispositivo, configurabili tramite rate_limits. Aumenta i limiti se molti sviluppatori accedono da un singolo indirizzo NAT aziendale condiviso. I rollout su larga scala mostra come dimensionarli. I limiti si applicano solo al flusso di accesso, non all'inferenza.

Postura di conformità

• Residenza dei dati: il piano dati del gateway stesso non invia nulla ad Anthropic a meno che l'API Anthropic non sia un upstream configurato; quando lo è, il tuo accordo di gestione dei dati esistente si applica al percorso di inferenza. Telemetria, audit, identità e impostazioni vanno solo alle destinazioni che configuri.
• Traffico del processo host: il processo host è il Claude Code CLI. Il claude gateway viene eseguito secondo le stesse regole di terze parti delle distribuzioni Amazon Bedrock e Google Cloud's Agent Platform e non invia nulla ad Anthropic. Prima della v2.1.227, il processo host inviava telemetria di avvio come versione del prodotto e piattaforma, che l'impostazione di CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 nell'ambiente del container disattivava. Quelle versioni inviavano anche una richiesta HEAD all'avvio, senza corpo o credenziali, a /api/hello su https://api.anthropic.com, o su ANTHROPIC_BASE_URL quando l'ambiente lo impostava, a meno che l'ambiente non impostasse anche una variabile proxy come HTTPS_PROXY o un certificato client mTLS. Ignoravano la risposta, quindi bloccare quella richiesta al firewall di uscita non influenzava il gateway.
• Analitiche client: il CLI disabilita la sua stessa analittica di utilizzo e segnalazione degli errori mentre è connesso a un gateway. Prima del primo accesso, il CLI invia comunque eventi di avvio ad Anthropic, incluso su macchine le cui impostazioni gestite forzano l'accesso al gateway. Per disattivare anche quelli, fornisci DISABLE_TELEMETRY nelle stesse impostazioni gestite lato client che forzano l'accesso al gateway.
• Segnalazione degli errori: il CLI disattiva la segnalazione degli errori ogni volta che le sue richieste di modello vanno a qualsiasi endpoint diverso dall'API di prima parte di Anthropic, come Amazon Bedrock o un ANTHROPIC_BASE_URL personalizzato.
• Macchine client: i CLI degli sviluppatori inviano comunque controlli del nome host WebFetch e controlli della versione ad Anthropic a meno che CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 e skipWebFetchPreflight: true non siano impostati. Consulta utilizzo dei dati.
• Valutazioni del sondaggio: mentre è connesso a un gateway, il CLI disabilita il caricamento della valutazione legato ad Anthropic insieme ai flussi di analitiche, quindi non invia valutazioni ad Anthropic.
• Condivisione della trascrizione: scegliere Sì su un prompt di condivisione della trascrizione di un sondaggio scrive un file locale sotto ~/.claude/feedback-bundles/ invece di caricare su Anthropic.
• Aggiornamenti client: i controlli di aggiornamento sono separati dal traffico del gateway. Fissa le versioni attraverso la tua distribuzione e imposta DISABLE_UPDATES se i laptop non devono recuperare le versioni. DISABLE_AUTOUPDATER interrompe solo gli aggiornamenti in background mentre claude update funziona ancora.
• TLS: servi public_url su HTTPS in produzione, sia dal listener proprio del gateway tramite listen.tls che da un ingress che termina TLS davanti alle repliche HTTP semplici, con listen.public_url impostato in entrambi i casi. Il gateway non rifiuta HTTP semplice. L'IdP deve servire HTTPS in produzione, e Postgres supporta ?sslmode=require. Imposta Strict-Transport-Security al tuo ingress.
• Divulgazione di vulnerabilità: segui Segnalazione di problemi di sicurezza

Troubleshooting

Per domande e feedback, utilizza il supporto Claude Code, oppure apri un problema nel repository GitHub di Claude Code. Quando segnali un problema, includi:

• Gateway issue: lo stderr del gateway per la finestra rilevante, il tuo gateway.yaml con i segreti oscurati, la versione del gateway, mostrata nella pagina di destinazione in / e nell'intestazione della risposta x-cc-gateway-version in /managed/settings, e cosa è cambiato di recente
• Login issue: lo sviluppatore esegue claude --debug-file ./claude-debug.txt, riproduce il problema e invia quel file più il log di audit del gateway per la stessa finestra
• Inference issue: il modello richiesto, gli upstream configurati e il log di audit del gateway per la richiesta, che registra quale upstream l'ha servita e lo stato della risposta

Lo stderr del gateway include il flusso di eventi di audit, il log di audit registra le identità degli sviluppatori e il file di debug registra l'output di hook e MCP server dalla macchina dello sviluppatore. Rivedi e oscura questi elementi prima di pubblicare su un problema pubblico.

Il messaggio Cloud gateway sign-in was not completed nomina il nome host del gateway. Quando Claude Code ha sia l'impronta digitale fissata che quella presentata, il messaggio mostra anche i primi 16 caratteri di ciascuna.

Se Claude Code segnala couldn't load your organization's managed settings dopo un accesso al gateway, Claude Code nomina il motivo, si riavvia sul posto e riprende la conversazione. Se Claude Code non può riavviarsi, ad esempio in una sessione in background, Claude Code termina la sessione e mantiene l'accesso.

Correlati

• Panoramica del gateway delle app Claude: quickstart e connessione dello sviluppatore
• Riferimento di configurazione: ogni opzione di gateway.yaml