Distribuzione e operazioni del gateway delle app Claude

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 }.

Per supporto con un provider di identità non trattato sopra, vedi Troubleshooting.

​

Distribuzione

Il gateway è un singolo binario Linux. Si scala orizzontalmente perché le repliche sono senza stato e Postgres è il livello di coordinamento condiviso. Eseguilo come esegui i servizi senza stato nel tuo ambiente. Il resto di questa sezione afferma cosa l’immagine ha bisogno, con brevi note per Kubernetes e Cloud Run. Il gateway è progettato per funzionare all’interno della tua rete, perché contiene le tue credenziali upstream e agisce come l’unico punto di uscita per l’inferenza. Può funzionare ovunque i tuoi sviluppatori e il tuo IdP possono raggiungere su HTTPS; trattalo come qualsiasi altro servizio che contiene una credenziale di produzione. Alcune decisioni modellano la distribuzione oltre a dove viene eseguita:

• Costo: non c’è una licenza separata o una tassa per posto per il gateway; fa parte del binario claude. Paghi per l’inferenza attraverso il tuo impegno cloud o Anthropic esistente, più il calcolo per il container e il tuo collettore di telemetria.
• 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. Il CLI memorizza la sua impronta digitale di fiducia e le credenziali per nome host del gateway, quindi diversi team possono connettersi a gateway diversi senza conflitto. Per servire più emittenti OIDC, esegui istanze separate.
• Serverless: Cloud Run funziona; imposta min-instances: 1 per evitare il cold start della scoperta OIDC. Lambda e Cloud Functions no, 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; l’esempio elaborato di Google Cloud ha 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.

​

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

​

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

​

Invia l’URL del gateway alle macchine degli sviluppatori

Una volta che il gateway è in servizio, invia forceLoginMethod e forceLoginGatewayUrl 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. Consulta Impostazioni gestite lato client per i percorsi dei file.

​

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, auth.denied, access.denied, inference, managed.serve, spend.blocked, e admin.denied. I campi variano per evento:
  • Gli eventi di mint e refresh riusciti portano sub, email, client_ip, e il risultato
  • Gli eventi di negazione portano il motivo, il percorso e l’IP client, poiché nessuna identità esiste al momento della negazione
  • inference registra quale upstream ha servito la richiesta e lo stato della risposta
  • admin.denied registra un tentativo di autenticazione dell’API admin rifiutato con il motivo (invalid_key o no_credentials), IP client, metodo e percorso, senza il materiale della chiave 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 info, warn, o error, con info come predefinito. 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. Un gateway in esecuzione serve anche una descrizione dei percorsi e delle forme di richiesta che accetta in <public_url>/protocol, abbinata alla versione che stai eseguendo. I contenuti non sono stabili tra le versioni.

​

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, e i nuovi accessi e aggiornamenti falliscono. 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, 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. Se la tua policy di sicurezza proibisce DDL dal ruolo dell’applicazione, pre-crea queste tabelle e _migrations con un ruolo admin e concedi al ruolo dell’app SELECT, INSERT, UPDATE, DELETE su ciascuno. 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 è sicuro in qualsiasi momento. Il gateway esegue migrazioni dello schema all’avvio, il che significa che distribuire il nuovo binario auto-migra il database. Se il ruolo del database non può eseguire DDL, pre-crea lo schema, inclusa la tabella _migrations seminata alla versione corrente; altrimenti l’avvio fallisce tentando CREATE TABLE. 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 in uscita 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 come l’IdP e le destinazioni OTLP 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 lo sviluppo locale rispetto a un IdP loopback o collettore, imposta CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 nell’ambiente del gateway; lascialo non impostato in produzione.

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 una tantum 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 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 CLI di Claude Code, che può inviare analitiche di avvio e controlli di aggiornamento ad Anthropic. Per distribuzioni con uscita ristretta, imposta CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 nell’ambiente del container del gateway.
• Analitiche client: il CLI disabilita la sua stessa analittica di utilizzo mentre è connesso a un gateway, e la segnalazione degli errori è disattivata per impostazione predefinita su superfici API di terze parti.
• 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: la credenziale del gateway disabilita il sink di valutazione legato ad Anthropic, quindi le valutazioni non vengono inviate 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. 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

​

Risoluzione dei problemi

Per domande e feedback, usa Supporto di Claude Code, o apri un problema nel repository GitHub di Claude Code. Quando segnali un problema, includi:

• Problema del gateway: lo stderr del gateway per la finestra rilevante, il tuo gateway.yaml con i segreti redatti, la versione del gateway, mostrata nella pagina di destinazione in / e nell’intestazione della risposta x-cc-gateway-version su /managed/settings, e cosa è cambiato di recente
• Problema di accesso: lo sviluppatore esegue claude --debug-file ./claude-debug.txt, riproduce, e invia quel file più il log di audit del gateway per la stessa finestra
• Problema di inferenza: 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. Rivedere e oscurare questi elementi prima di pubblicare in un problema pubblico.

​

Correlati

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