Gateway di app Claude per Amazon Bedrock, 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 agli elenchi di modelli consentiti e alle politiche di impostazioni gestite. 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 autorizzazioni, e uno sviluppatore non può ignorare 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, come Datadog, Splunk o ClickHouse, 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, 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
  # Obbligatorio dietro qualsiasi proxy che termina TLS. Utilizzato per l'IdP
  # redirect_uri e il documento di discovery.
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com        # deve servire /.well-known/openid-configuration
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]        # rifiuta id_tokens al di fuori della tua organizzazione
  userinfo_fallback: true                  # per IdP il cui id_token omette email/groups; innocuo altrimenti

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}        # openssl rand -base64 32
  ttl_hours: 1                             # limita anche la latenza di revoca su deprovision IdP

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}    # aggiungi ?sslmode=require per Postgres gestito

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {} # vuoto: catena di credenziali predefinita AWS
# (IRSA, ruolo attività EC2/ECS, variabili env, ~/.aws)

# I modelli vengono tradotti per upstream automaticamente. Il catalogo integrato
# mappa claude-opus-4-8 a us.anthropic.claude-opus-4-8 e così via per ogni
# modello Claude supportato da Bedrock. Imposta false e aggiungi un elenco `models:` per
# esporre solo modelli specifici.
auto_include_builtin_models: true

services:
  gateway:
    image: <your-registry>/claude-gateway:<version>
    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
      # Credenziali AWS: in produzione, ometti questi e usa un ruolo di istanza
      # Per il test locale di Compose, passa i tuoi:
      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.408Z info migration 1 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
}

​

Connetti gli sviluppatori

​

Imposta l’URL del gateway

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

​

Pipeline CI e macchine remote

​

Cosa viene applicato agli sviluppatori

• Accesso ai modelli: le richieste per modelli che la politica non concede restituiscono 400 e il selettore /model viene filtrato all’elenco di autorizzazione availableModels della politica. Imposta enforceAvailableModels: true nella politica in modo che l’opzione Predefinita si risolva in un modello all’interno di availableModels invece che al valore predefinito integrato di Claude Code; senza di esso, Predefinita rimane selezionabile e viene rifiutata al momento della richiesta se quel modello non è concesso.
• Destinazione telemetria: quando è configurato l’inoltro di telemetria, l’endpoint di esportazione OTLP è bloccato al gateway e la configurazione spinta dal gateway sostituisce le variabili OTEL_* impostate localmente.
• Credenziali: il token del gateway è l’unica credenziale della sessione. ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper e qualsiasi accesso precedente a claude.ai vengono ignorati mentre connesso, quindi gli sviluppatori non hanno bisogno di disconnettersi da claude.ai per primo.
• Impostazioni gestite: le chiavi bloccate non possono essere ignorate localmente. Il CLI applica la politica all’avvio e su ogni sondaggio orario.
• Avvio: le sessioni connesse escono all’avvio con un errore dopo circa 10 secondi quando il gateway è irraggiungibile, piuttosto che iniziare senza le loro impostazioni.
• Deprovision: una sessione il cui utente è disabilitato nell’IdP scade entro ttl_hours quando il prossimo aggiornamento fallisce.

​

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 Google Cloud, con Cloud Run, Cloud SQL e Secret Manager, vedi Distribuisci su Google Cloud.