Gateway di app Claude per Amazon Bedrock, Claude Platform su AWS, Google Cloud e Microsoft Foundry

• Perché Claude apps gateway, cosa aggiunge rispetto all’esecuzione della tua, e quando qualcos’altro si adatta meglio
• Una guida rapida con prerequisiti che porta un gateway da zero a uno sviluppatore connesso
• Connessione degli sviluppatori, inclusa l’impostazione dell’URL del gateway attraverso le impostazioni gestite
• Disponibilità e limitazioni che coprono quali funzionalità di Claude Code funzionano attraverso il gateway e cosa supporta il server

Perché Claude apps gateway

• Credenziali: la chiave API upstream o la credenziale cloud vive solo nella tua infrastruttura. Gli sviluppatori si autenticano con SSO aziendale e ricevono token bearer di breve durata, quindi l’offboarding avviene nel tuo IdP. Deprovision un utente e il suo accesso al gateway scade entro la durata della sessione, un’ora per impostazione predefinita.
• Controllo di accesso: i tuoi gruppi IdP si mappano ad allowlist di modelli, politiche di impostazioni gestite e upstream. Il gateway applica l’accesso ai modelli lato server, rifiutando le richieste per modelli non concessi, e seleziona la politica di impostazioni gestite di ogni gruppo, che il CLI applica al livello di impostazioni gestite. Diversi team ottengono diversi modelli, strumenti e permessi, e uno sviluppatore non può sovrascrivere ciò che la sua politica blocca.
• Consegna delle impostazioni: il gateway consegna le impostazioni gestite ai client connessi stesso, prendendo il posto delle impostazioni gestite dal server dalla console amministratore di claude.ai.
• Telemetria: ogni destinazione configurata riceve metriche OpenTelemetry Protocol (OTLP) con conteggi di token, modello, identità dell’utente e latenza per impostazione predefinita, con log e tracce come opt-in per destinazione.
• Instradamento upstream: i client parlano l’API Anthropic Messages al gateway, e il gateway traduce per ogni upstream, sia Bedrock, Claude Platform su AWS, Agent Platform di Google Cloud, Foundry o l’API Anthropic, con failover tra loro. Puoi cambiare regioni, provider o ordine di failover senza che gli sviluppatori se ne accorgano o riconfigurino.

Altre implementazioni di gateway

Guida rapida

Prerequisiti

Passaggi

listen:
  host: 0.0.0.0
  port: 8080
  # Required unless host is a loopback address. Used for the IdP
  # redirect_uri and the discovery document.
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com        # must serve /.well-known/openid-configuration
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]        # reject id_tokens outside your org
  userinfo_fallback: true                  # for IdPs whose id_token omits email/groups; harmless otherwise

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}        # openssl rand -base64 32
  ttl_hours: 1                             # also bounds revocation latency on IdP deprovision

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}    # add ?sslmode=require for managed Postgres

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {} # empty: AWS default credential chain
# (IRSA, EC2/ECS task role, env vars, ~/.aws)

# Models are translated per upstream automatically. The built-in catalog
# maps claude-opus-4-8 to us.anthropic.claude-opus-4-8 and so on for every
# Bedrock-supported Claude model. Set false and add a `models:` list to
# expose only specific models.
auto_include_builtin_models: true

services:
  gateway:
    image: registry.example.com/claude-gateway:2.1.198
    ports: ["8080:8080"]
    volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]
    environment:
      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
      GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}
      GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway
      # AWS credentials: in production, omit these and use an instance
      # role. For local Compose testing, pass through your own:
      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
      AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}
    depends_on:
      postgres:
        condition: service_healthy
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gw"]
      interval: 5s
    volumes: ["pgdata:/var/lib/postgresql/data"]
volumes: { pgdata: }

{"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}
[gateway] 2026-06-10T17:03:21.395Z info waiting for migration lock (another replica may be migrating; check pg_locks for key 6775156 if this persists)
[gateway] 2026-06-10T17:03:21.408Z info migration 1 applied
…
[gateway] 2026-06-10T17:03:21.431Z info migration 6 applied
[gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

{
  "issuer": "https://claude-gateway.internal.example.com",
  "device_authorization_endpoint": "…/oauth/device_authorization",
  "token_endpoint": "…/oauth/token",
  "grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
}

curl -s -X POST https://claude-gateway.internal.example.com/oauth/device_authorization | jq

{
  "device_code": "…",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://claude-gateway.internal.example.com/device",
  "verification_uri_complete": "https://claude-gateway.internal.example.com/device?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

Connettere gli sviluppatori

openssl x509 -noout -fingerprint -sha256 -in cert.pem | cut -d= -f2 | tr -d : | tr 'A-F' 'a-f'

Impostare l’URL del gateway

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

Impostare l’URL del gateway nelle impostazioni utente

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}

• Solo impostazioni utente: Claude Code legge le due chiavi da ~/.claude/settings.json, non dal .claude/settings.json o dal .claude/settings.local.json di un progetto.
• Le impostazioni gestite le disattivano: una volta che le impostazioni di un amministratore raggiungono la macchina tramite un file di impostazioni gestite, un plist macOS o una policy HKLM di Windows, oppure un policy helper, Claude Code ignora un gateway indicato nelle impostazioni utente.

Consentire un gateway su uno spazio di indirizzi pubblico di tua proprietà

{
  "gatewayInternalNetworks": ["203.0.113.0/24"]
}

• Ogni voce è un blocco IPv4 scritto come primo indirizzo e un prefisso da /8 a /32.
• L’elenco contiene al massimo quattro blocchi, e nessuno si sovrappone a un altro.
• Nessun blocco si sovrappone allo spazio di indirizzi privato: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16 e 100.64.0.0/10. /login accetta già un gateway lì senza questa chiave.
• Nessun blocco si sovrappone a uno spazio che non è mai la rete di un’organizzazione: 198.18.0.0/15 e 192.0.0.0/24, che i client VPN e NAT64 usano come indirizzi locali; gli intervalli di documentazione 192.0.2.0/24, 198.51.100.0/24 e 203.0.113.0/24; e gli intervalli riservati 0.0.0.0/8, 192.88.99.0/24 e multicast 224.0.0.0/4. Puoi dichiarare blocchi all’interno di 240.0.0.0/4, che alcune reti di grandi dimensioni usano come spazio unicast interno.

• Ogni indirizzo a cui si risolve il nome host del gateway si trova all’interno di quell’unico blocco. Claude Code rifiuta un nome che ha anche record al di fuori di esso, compresi gli indirizzi privati e IPv6.
• La macchina dello sviluppatore si connette dall’interno dello stesso blocco. Claude Code rifiuta una macchina dietro NAT, all’interno di un container o di WSL2, o su una VPN il cui pool di indirizzi si trova al di fuori del blocco, e indica l’indirizzo da cui la macchina si è connessa.
• La connessione è diretta. Se HTTPS_PROXY si applica all’host del gateway, /login rifiuta e indica la voce NO_PROXY da aggiungere.

Fornire la policy alle sessioni di Claude Desktop

Quali macchine richiedono l’opt-in

Impostare l’opt-in

Limitare le impostazioni padre

• Voci deny: inoltrate solo con il loro path o name e la modalità.
• Voci di file con mode: mask: inoltrate solo come sentinella, come maschera dell’intero file il cui injectHosts è l’elenco vuoto, quindi il proxy non sostituisce mai il valore reale per una voce fornita dal padre su nessuna piattaforma. Vengono eliminati anche tutti i campi di mascheramento strutturato, quindi un pattern di estrazione fornito dal padre non può sostituire una maschera più rigorosa impostata da un’altra origine per lo stesso percorso.
• Voci envVars con mode: mask: non inoltrate. deny è l’unica restrizione che il canale padre può esprimere tramite le voci envVars.
• awsPairs e sigv4: inoltrati solo come restrizioni. Di sigv4 vengono mantenuti solo i valori deny, e un padre che definisce un qualsiasi blocco sigv4 fissa tutte e tre le forme di richiesta, streaming, presigned e sigv4a, su deny. Una coppia awsPairs non viene mai inoltrata in una forma che possa rifirmare; una coppia che indica una delle variabili AWS convenzionali viene sostituita da una voce inerte che mantiene soppresso l’abbinamento automatico di AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN.

Distribuire i blocchi

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge",
  "allowManagedPermissionRulesOnly": true,
  "allowManagedMcpServersOnly": true,
  "allowManagedHooksOnly": true,
  "allowedMcpServers": [{ "serverUrl": "https://mcp.internal.example.com/*" }],
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": ["github.com", "*.npmjs.org"]
    },
    "filesystem": {
      "allowManagedReadPathsOnly": true,
      "denyRead": ["~/"],
      "allowRead": ["~/projects"]
    }
  }
}

Comportamento dei blocchi tra le origini

• Domini di rete: un blocco con un elenco di domini gestiti vuoto blocca tutto il traffico in uscita dalla sandbox.
• Server MCP: un blocco senza allowedMcpServers in nessuna origine di amministrazione né nelle impostazioni fornite dal padre carica ogni server che deniedMcpServers non blocca.
• Percorsi di lettura: le voci allowRead riconsentono solo percorsi all’interno delle aree denyRead, quindi abbinale a un denyRead gestito.

Impostazioni non coperte dai blocchi

• forceLoginOrgUUID: Claude Code rispetta un valore fornito dal padre quando le impostazioni gestite che applica non impostano un UUID dell’organizzazione. L’accesso al gateway non controlla questa chiave. Un UUID dell’organizzazione nelle impostazioni gestite applicate da Claude Code blocca il valore del padre ed è l’UUID dell’organizzazione che Claude Code impone. Se la tua flotta fissa un’organizzazione Anthropic, consulta Quale origine gestita fornisce le chiavi di accesso per sapere dove impostare forceLoginOrgUUID.
• allowedMcpServers: Claude Code rispetta un’allowlist fornita dal padre quando non è in vigore alcun elenco di amministrazione. allowManagedMcpServersOnly non la blocca, perché il blocco impone come valore gestito l’elenco che prevale, compreso uno fornito dal padre quando nessuna origine di amministrazione fornisce un elenco. Un elenco nell’origine di amministrazione con priorità più alta blocca quello del padre ed è l’elenco che Claude Code impone, quindi imposta allowedMcpServers lì, accanto al blocco. Prima della v2.1.223, un valore per una delle due chiavi in qualsiasi origine di amministrazione bloccava quello del padre.
• availableModels: Claude Code rispetta un elenco di modelli fornito dal padre quando l’origine gestita prevalente non ne imposta uno. Se la tua flotta limita i modelli, imposta availableModels nell’origine prevalente.
• allowedProviders: Claude Code rispetta un’allowlist dei provider API fornita dal padre quando l’origine gestita prevalente non ne imposta una. Se la tua flotta limita i provider API che gli sviluppatori possono usare, imposta allowedProviders nell’origine prevalente. Richiede Claude Code v2.1.285 o successivo.
• strictKnownMarketplaces: Claude Code rispetta un’allowlist di marketplace di plugin fornita dal padre quando l’origine gestita prevalente non ne imposta una. Claude Desktop 2.16120.0 o successivo ne invia una quando la sua configurazione gestita disattiva i marketplace di plugin aggiunti dagli utenti. Se la tua flotta limita i marketplace, imposta strictKnownMarketplaces nell’origine prevalente. Richiede Claude Code v2.1.282 o successivo.
• blockedMarketplaces: una blocklist di marketplace fornita dal padre supera il filtro e si aggiunge a qualsiasi blocklist impostata da un’origine gestita, poiché una blocklist può solo restringere ulteriormente. Richiede Claude Code v2.1.282 o successivo.
• strictPluginOnlyCustomization: questa chiave supera il filtro indipendentemente da qualsiasi blocco, e fa sì che Claude Code ignori le personalizzazioni dello sviluppatore, compresi gli hook di protezione. Nessun blocco la blocca.

Come hanno effetto le chiavi di hook e skill nelle impostazioni padre

• Si fermano: gli hook utente, di progetto e locali, più gli hook dichiarati nel frontmatter degli agenti o nell’opzione settings dell’SDK.
• Continuano a essere eseguiti: le callback degli hook SDK della tua applicazione e gli hook di un amministratore provenienti dalle impostazioni gestite. La tua applicazione non può disattivare gli hook dell’amministratore.

Connettere Claude Desktop

Pipeline CI e macchine remote

Cosa viene imposto agli sviluppatori

• Accesso ai modelli: le richieste per modelli che la policy non concede restituiscono 400, e il selettore /model è filtrato in base all’allowlist availableModels della policy. Questo include il modello con cui una sessione si avvia prima che lo sviluppatore ne scelga uno; consulta Avviare le sessioni su un modello consentito dalla policy.
• Destinazione della telemetria: nelle sessioni in cui si è effettuato l’accesso tramite /login, la CLI invia le sue esportazioni OTLP/HTTP al gateway anziché a un OTEL_EXPORTER_OTLP_ENDPOINT impostato localmente, a meno che una policy non indichi il tuo collector come endpoint. Il gateway inoltra le esportazioni che riceve alle destinazioni in telemetry.forward_to.
  • Nelle sessioni incorporate avviate da Claude Desktop, la CLI invia le sue esportazioni all’OTEL_EXPORTER_OTLP_ENDPOINT configurato. La CLI allega il token di sessione del gateway a queste esportazioni solo quando quell’endpoint punta al gateway stesso.
  • Senza una destinazione configurata per un segnale, il gateway lo accetta e lo scarta.
  • Se raccogli già la telemetria di Claude Code direttamente, aggiungi il tuo collector come destinazione forward_to, oppure indicalo in una policy per saltare l’inoltro.
• Credenziali: il token del gateway è l’unica credenziale della sessione. I profili Anthropic e qualsiasi accesso precedente a claude.ai vengono ignorati mentre si è connessi, quindi gli sviluppatori non devono prima uscire da claude.ai. Per una credenziale ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN o apiKeyHelper configurata, o per una chiave API salvata da un precedente accesso alla Claude Console, consulta Administrator policy requires a Cloud gateway sign-in.
• Impostazioni gestite: le chiavi bloccate non possono essere sovrascritte localmente. La CLI applica la policy all’avvio e applica le modifiche a ogni polling orario, a parte le modifiche che si applicano solo al successivo avvio.
• Avvio con il gateway irraggiungibile: le sessioni con accesso effettuato terminano all’avvio con un errore dopo circa 10 secondi anziché avviarsi senza le proprie impostazioni.
• Avvio dopo che il gateway ha terminato la sessione: consulta Imporre l’avvio fail-closed per gli avvii che si aprono senza accesso al gateway e per quelli che terminano quando il gateway risponde con un 401.
• Deprovisioning: una sessione il cui utente è disabilitato nell’IdP scade entro ttl_hours quando il rinnovo successivo fallisce.
• Uscita: /logout elimina la credenziale del gateway dalla macchina dello sviluppatore.
  • Quando il documento di discovery del gateway pubblicizza un revocation_endpoint con lo stesso schema, host e porta dell’URL del gateway, /logout invia anche i token memorizzati a quell’endpoint, in modo che il gateway possa terminare la sessione dal proprio lato. La richiesta è best effort, quindi l’uscita si completa sulla macchina dello sviluppatore indipendentemente dal fatto che l’endpoint risponda. La revoca richiede Claude Code v2.1.275 o successivo sulla macchina dello sviluppatore.
  • Il server gateway incluso nel binario claude non ne pubblicizza alcuno, quindi un’uscita da esso termina la sessione solo sulla macchina dello sviluppatore. Per forzare la chiusura delle sessioni lato server, consulta Rotazione del segreto JWT.

Cosa può vedere l’organizzazione

Disponibilità e limitazioni

Passaggi successivi

• Espandi gateway.yaml oltre la configurazione minima, ad esempio per aggiungere RBAC per gruppo, failover multi-upstream o destinazioni di telemetria. Il riferimento di configurazione copre ogni opzione.
• Passa da Compose a una distribuzione di produzione su Kubernetes o Cloud Run, configura correttamente il tuo IdP e rivedi il modello di sicurezza. La guida di distribuzione e operazioni copre la configurazione per IdP, i requisiti dell’immagine container, i probe di salute e la risoluzione dei problemi.
• Metti limiti di spesa su singoli sviluppatori o gruppi in modo che un carico di lavoro incontrollato non possa consumare il tuo intero impegno. Limiti di spesa copre l’API amministratore e come funziona l’applicazione.
• Per un esempio completo su AWS, con ECS Fargate o EKS, Amazon RDS e Secrets Manager, vedi Distribuisci su AWS.
• Per un esempio completo su Google Cloud, con Cloud Run, Cloud SQL e Secret Manager, vedi Distribuisci su Google Cloud.