Bereitstellung und Betrieb des Claude-Apps-Gateways

1. Richten Sie Ihren Identitätsanbieter ein: Registrieren Sie den OAuth-Client und überprüfen Sie die IdP-spezifischen Hinweise für Okta, Entra und Google
2. Stellen Sie das Gateway bereit: Erstellen Sie ein gepinntes Container-Image und führen Sie es auf Kubernetes, Cloud Run oder Ihrer eigenen Plattform aus. Dieser Abschnitt behandelt auch Kosten-, Bypass-, Multi-Gateway- und Serverless-Entscheidungen
3. Richten Sie den Betrieb ein: Protokolle, Integritätsprüfungen, Ausfallverhalten, Geheimnisrotation und Upgrades. Referenzmaterial für die Einrichtung von Überwachung und Runbooks
4. Überprüfen Sie die Sicherheitslage: Welche Daten wohin fließen, das Bedrohungsmodell und Compliance-Antworten. Referenzmaterial für eine Sicherheitsüberprüfung

​

Identitätsanbieter-Setup

• Stellt /.well-known/openid-configuration über HTTPS in der Produktion bereit; das Gateway akzeptiert einen http:// Aussteller, und ein Loopback-Aussteller erfordert zusätzlich CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
• Unterstützt den Authorization-Code-Flow. PKCE (Proof Key for Code Exchange) ist standardmäßig aktiviert; deaktivieren Sie es mit oidc.use_pkce: false für IdPs, die es nicht unterstützen
• Gibt email und optional groups im id_token zurück, oder stellt sie vom Userinfo-Endpoint mit oidc.userinfo_fallback: true bereit

• Okta: Der Org-Autorisierungsserver unter https://example.okta.com gibt einen dünnen id_token zurück, der email und groups auslässt, daher setzen Sie oidc.userinfo_fallback: true, wenn Sie ihn als issuer verwenden. Ein benutzerdefinierter Autorisierungsserver wie https://example.okta.com/oauth2/default, der email und optional groups im id_token enthält, gibt sie direkt aus und benötigt keinen Fallback. Okta gibt groups nur aus, wenn der groups-Scope in oidc.scopes angefordert wird und der Gruppen-Claim-Filter der App dies zulässt; userinfo_fallback kann einen Claim nicht ausfüllen, nach dem der IdP nicht gefragt wurde.
• Microsoft Entra ID: issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra gibt Gruppen-Object-IDs statt Namen aus, daher verwenden Sie die GUIDs in managed.policies.match.groups, oder verwenden Sie App-Rollen für lesbare Namen. Wenn Ihr Mandant Rollen unter roles statt groups ausgibt, setzen Sie oidc.groups_claim: roles.
• Google Workspace: issuer = https://accounts.google.com. Googles id_token enthält keine Gruppen. Um gruppenbasierte allowed_groups oder managed.policies mit Google als IdP zu verwenden, konfigurieren Sie oidc.google_groups, das die Gruppen jedes Benutzers über die Admin SDK Directory API mit einem Service-Account mit Domain-Wide-Delegation nachschlägt. Ohne dies verwenden Sie oidc.allowed_email_domains für Mitgliedschafts-Gating und managed.policies.match.email_domain für Richtlinienzuweisung. Google ignoriert auch den Standard-Scope offline_access. Für Refresh-Tokens setzen Sie oidc.scopes: [openid, profile, email] und oidc.extra_auth_params: { access_type: offline, prompt: consent }.

​

Bereitstellung

• Kosten: Keine separate Lizenz oder Pro-Sitz-Gebühr. Das Gateway ist Teil der claude-Binärdatei, daher zahlen Sie für Inferenz über Ihr bestehendes Engagement, plus die Berechnung, auf der es läuft.
• Bypass: Das Gateway erzwingt nicht, dass die einzige Route zu einem Modell durch es führt. Ein Entwickler mit seinen eigenen Anmeldedaten kann den Anbieter immer noch direkt aufrufen, daher ist das Schließen dieses Pfads eine Netzwerkrichtlinien-Entscheidung, z. B. das Blockieren von Egress zu api.anthropic.com außer vom Gateway. Das Blockieren dieses Egress bricht auch die WebFetch-Domain-Sicherheitsprüfung, die api.anthropic.com von jeder Entwicklermaschine aufruft. Setzen Sie skipWebFetchPreflight: true in der verwalteten Richtlinie, um sie zu deaktivieren.
• Mehrere Gateways: Jedes ist eine separate Bereitstellung mit seiner eigenen Konfiguration, und die CLI speichert Vertrauen und Anmeldedaten pro Gateway-Hostname, daher können Teams verschiedene Gateways ohne Konflikte verwenden. Um mehrere OIDC-Aussteller zu bedienen, führen Sie separate Instanzen aus.
• Serverless: Cloud Run funktioniert, wenn Sie min-instances: 1 setzen, um kalte OIDC-Erkennung zu vermeiden. Lambda und Cloud Functions funktionieren nicht, da das Gateway ein langlebiger HTTP-Server ist.

• Bei jedem Upstream außer provider: anthropic schreibt das Gateway einen SSE-ping, sobald ein Stream etwa 15 Sekunden lang stumm war.
• Bei provider: anthropic leitet das Gateway die Antwort unverändert weiter, einschließlich der eigenen Pings der Anthropic-API.

​

Container-Image

1. Laden Sie den Linux-Build für Ihre Image-Architektur aus einer gepinnten Version herunter; siehe Installieren Sie eine bestimmte Version für die Download-URL.
2. Überprüfen Sie es gegen die GPG-signierte manifest.json der Version, wie in Binäre Integrität und Code-Signierung beschrieben.
3. Kopieren Sie es in den Build-Kontext.

• Ein glibc-basiertes Image: Die einzigen dynamischen Abhängigkeiten des glibc-Builds sind glibc-Bibliotheken. Musl-basierte Images benötigen den linux-x64-musl- oder linux-arm64-musl-Build plus zusätzliche Pakete; siehe Alpine-Linux-Setup.
• Ein beschreibbares Zustandsverzeichnis: Das Gateway läuft als jeder Benutzer, aber minimale Images haben kein beschreibbares Home. Setzen Sie CLAUDE_CONFIG_DIR auf einen beschreibbaren Pfad wie /tmp/.claude.
• Der Container-Befehl: claude gateway --config /etc/claude/gateway.yaml, mit der Konfigurationsdatei schreibgeschützt eingebunden und Geheimnissen als Umgebungsvariablen bereitgestellt; das Gateway lauscht auf listen.port, Standard 8080.

​

Kubernetes

• Binden Sie die Konfiguration von einer ConfigMap und Geheimnisse von einem Secret ein; referenzieren Sie Geheimnisse in der YAML über ${file:/path/to/secret} oder als Umgebungsvariablen
• Beenden Sie TLS am Ingress und setzen Sie listen.public_url auf den Ingress-Hostnamen
• Zeigen Sie die Readiness-Probe auf GET /readyz und die Liveness-Probe auf GET /healthz

​

Cloud Run

• Lassen Sie listen.port bei seinem Standard von 8080, das Cloud Runs Standard-PORT entspricht, oder setzen Sie port: ${PORT}
• Setzen Sie public_url auf den extern erreichbaren Ursprung. Für die Produktion ist dies normalerweise der Hostname eines internen Load Balancers, da /login öffentliche Adressen ablehnt und die *.run.app-URL zu einer aufgelöst wird, daher funktioniert die Cloud-Run-URL allein nur für einen curl- oder Browser-Smoke-Test. Die Ausnahme ist ein Netzwerk, in dem *.run.app privat über Private Service Connect und eine Cloud-DNS-Private-Zone aufgelöst wird; in dieser Topologie ist die Cloud-Run-URL eine gültige public_url. Das Google-Cloud-Beispiel behandelt beide.
• Binden Sie die Konfiguration als Secret-Volume ein
• Setzen Sie min-instances: 1, um kalte OIDC-Erkennung bei der ersten Anfrage zu vermeiden

​

Pushen Sie die Gateway-URL zu Entwicklermaschinen

​

Große Rollouts

• Das Gateway kann nicht über Ihren Load Balancer hinaussehen. Ohne listen.trusted_proxies scheint jeder Entwickler von der Adresse des Load Balancers zu kommen und teilt sich ein Limit. Setzen Sie es vor allem anderen. Das Gateway protokolliert eine Warnung, wenn es zum ersten Mal einen X-Forwarded-For-Header ignoriert.
• Viele Entwickler teilen sich wenige NAT- oder VPN-Egress-Adressen. Sie teilen sich die Limits dieser Adressen, auch wenn trusted_proxies richtig ist. Erhöhen Sie rate_limits, um zu passen.

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

​

Betrieb

​

Protokolle

• Audit-Events: einzeilige JSON pro sicherheitsrelevantes Event. Leiten Sie stderr an Ihren Log-Aggregator. Die ausgegebenen Events umfassen 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 und admin.limit.delete. Felder variieren je nach Event:
  • Erfolgreiche Mint- und Refresh-Events tragen sub, email, client_ip und das Ergebnis
  • auth.denied und access.denied tragen den Grund und die Client-IP, plus den Anfragepfad für auth.denied, da bei diesen Ablehnungen keine Benutzeridentität existiert. Zwei access.denied-Gründe ändern, was das Event trägt:
    • xff_unparseable: das Event trägt auch den X-Forwarded-For-Eintrag, der nicht gelesen werden konnte
    • client_ip_unknown: das Event trägt keine Client-IP, da die Verbindung keine Peer-Adresse hatte, während eine access_control-Liste gesetzt war
  • access.public_client trägt die Client-IP der ersten Anfrage pro Prozess, die von einer öffentlichen Adresse ankommt, während access_control.allow_cidrs leer ist. Das Gateway bedient die Anfrage wie gewohnt; das Event signalisiert, dass das Gateway möglicherweise vom öffentlichen Internet erreichbar ist. Siehe die access_control-Referenz für das, was als öffentlich zählt, und für die empfohlene Allow-Liste.
  • inference zeichnet auf, welcher Upstream die Anfrage bedient hat und den Antwortstatus
  • desktop_bootstrap.denied zeichnet einen abgelehnten Claude Desktop Bootstrap-Abruf mit dem Grund (not_configured, policy_not_opted_in oder no_policy_matched) und der Identität des Benutzers auf
  • admin.denied zeichnet einen abgelehnten Admin-API-Auth-Versuch mit der Client-IP, Methode, Pfad und einem Grund auf, ohne das präsentierte Schlüsselmaterial: invalid_key, wenn ein x-api-key präsentiert wurde, aber keinen konfigurierten Schlüssel entsprach, bearer_rejected, wenn nur ein Authorization-Header präsentiert wurde und er sich nicht als Gateway-Sitzung in admin.admin_groups verifizierte, oder no_credentials, wenn keiner der Header präsentiert wurde
• Operationale Protokolle: lesbare [gateway]-präfixierte Zeilen für Boot, Warnungen und Upstream-Fehler. Die Umgebungsvariable CLAUDE_GATEWAY_LOG_LEVEL steuert die Ausführlichkeit und akzeptiert debug, info, warn oder error, mit info als Standard. Bei debug protokolliert jede Anmeldung und Aktualisierung auch die Namen, nicht die Werte, der Ansprüche im id_token, plus die Namen der userinfo-Ansprüche, wenn userinfo_fallback welche bereitgestellt hat, damit Sie email_claim- und groups_claim-Einstellungen diagnostizieren können, ohne PII zu protokollieren. Es beeinflusst keine Audit-Events, die immer ausgegeben werden.

​

Integrität

​

Gleichzeitige Upstream-Anfragen

• Fügen Sie Replikationen hinzu.
• Erhöhen Sie das Limit auf jeder Replikation. Setzen Sie die Umgebungsvariable BUN_CONFIG_MAX_HTTP_REQUESTS auf dem Gateway-Container auf eine ganze Zahl von 1 bis 65535, dann starten Sie den Container neu.

​

Ausfallverhalten

• Bestehende Sitzungen: Bearer-Tokens validieren lokal mit dem JWT-Geheimnis, Sitzungs-Refreshes berühren den Store nicht, und der Gateway-Prozess kann immer noch Inferenz bedienen
• Neue Anmeldungen: schlagen fehl, bis Postgres wiederhergestellt ist, da der Device-Flow und seine Rate-Limit-Zähler in Postgres leben
• Spend-Limit-Durchsetzung: schlägt während des Ausfalls offen fehl, daher fließt Inferenz weiterhin; schalten Sie es auf Fail-Closed um, wenn Sie lieber blockieren als ungemessen laufen möchten
• Readiness: standardmäßig meldet /readyz nicht bereit, sobald Postgres unerreichbar ist, daher schlägt jede Replikation ihre Readiness-Prüfung auf einmal fehl. Wo Verkehr nur Replikationen erreicht, die die Prüfung bestehen, schlägt der gesamte Verkehr, einschließlich Inferenz, die das Gateway immer noch bedienen könnte, beim Load Balancer fehl, bis Postgres wiederhergestellt ist. Die Liveness-Probe auf /healthz bleibt bestehen.

​

Readiness-Grace-Periode

​

JWT-Geheimnisrotation

1. Generieren Sie ein neues Geheimnis. Stellen Sie es dem session.jwt_secret-Array voran.
2. Rollen Sie die Bereitstellung aus. Neue Tokens signieren mit dem neuen Geheimnis; alte Tokens validieren immer noch.
3. Nach ttl_hours plus einer Marge entfernen Sie das alte Geheimnis und rollen erneut aus.

​

Postgres

​

Upgrades

• Das Drain-Fenster: setzen Sie die Umgebungsvariable CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS auf dem Gateway-Container auf eine positive ganze Zahl von Millisekunden, wie 120000. Das Gateway ignoriert einen Wert in jeder anderen Form, wie 120s, und behält den 25-Sekunden-Standard
• Die Grace Period Ihres Orchestrators: terminationGracePeriodSeconds auf Kubernetes oder stopTimeout auf Amazon ECS

• Amazon ECS on Fargate: stopTimeout erlaubt höchstens 120 Sekunden
• Cloud Run: stoppt eine Instanz 10 Sekunden nach SIGTERM, daher bekommen offene Streams dort höchstens 10 Sekunden, egal wie das Drain-Fenster ist

​

Sicherheit

​

Datenfluss

​

Bedrohungsmodell-Zusammenfassung

• Entwickler halten kurzlebige JWTs statt roher Upstream-Schlüssel. Das CLI-zu-Gateway-Bein verwendet den RFC-8628-Device-Grant, und der Gateway-Autorisierungs-Code-Austausch mit dem IdP führt PKCE in der Standard-Konfiguration aus, daher ist ein abgefangener IdP-Autorisierungs-Code nutzlos.
• Die Device-Verifikationsseite erzwingt Same-Origin-POST und ein Pro-IP-Rate-Limit pro RFC 8628 §5.1. Siehe User-Code-Brute-Force-Resistenz.
• Die Anfragen des Gateways an Ihren IdP, Ihre OTLP-Collector und provider: anthropic-Upstreams gehen durch einen Server-Side-Request-Forgery (SSRF)-Guard, der DNS auflöst, Link-Local- und Cloud-Metadata-Adressen plus Loopback standardmäßig blockiert und die Verbindung zur aufgelösten IP pinnt, daher können Operator-beeinflusste URLs nicht zu Cloud-Metadata-Endpoints umgeleitet werden. RFC-1918-Private-Bereiche sind absichtlich erlaubt, da IdPs und OTLP-Collector häufig auf privaten IPs leben. Für die anderen Provider weigert sich das Gateway, eine base_url zu akzeptieren, die eine dieser Adressen oder einen Metadata-Hostnamen benennt, wenn es die Konfiguration lädt, und das SDK des Providers verbindet sich dann ohne die DNS-Prüfung. Wenn Sie Proxy-Only-Egress aktivieren, verschiebt sich diese Adressprüfung zu Ihrem Forward-Proxy: Das Gateway übergibt Hostnamen und die Allowlist des Proxys muss diese Ziele ablehnen. Setzen Sie CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 in der Gateway-Umgebung nur, wenn etwas, das das Gateway erreichen muss, legitim auf Loopback lebt, wie ein lokaler Entwicklungs-IdP oder ein Sidecar-OTLP-Collector auf localhost. Die Variable lockert die Loopback-Blockade für jede Operator-konfigurierte URL und überspringt auch die Boot-Zeit-Warnung, die prüft, ob der Pod den Cloud-Metadata-Endpoint erreichen kann, daher bevorzugen Sie es, dem Collector seine eigene interne Adresse zu geben.

• Ein kompromittierter Gateway-Host: Der Host hält sowohl die Upstream-Anmeldedaten als auch verteilt verwaltete Einstellungen an jeden verbundenen Entwickler, daher ist die Kontrolle über die Gateway-Konfiguration vergleichbar mit der Kontrolle über Ihr MDM. Der Genehmigungsdialog der CLI für Shell-fähige Einstellungen begrenzt stille Änderungen, ersetzt aber nicht die Host-Sicherheit.
• Ein böswilliger OIDC-Anbieter: Der Anbieter signiert die id_tokens, denen das Gateway vertraut, daher kann er jede Identität behaupten. Das Überprüfen und Sichern Ihres IdP ist Ihre Verantwortung.

​

User-Code-Brute-Force-Resistenz

​

Compliance-Haltung

• Datenresidenz: Die Datenebene des Gateways selbst sendet nichts an Anthropic, es sei denn, die Anthropic-API ist ein konfigurierter Upstream; wenn sie es ist, gilt Ihre bestehende Datenbehandlungsvereinbarung für den Inferenz-Pfad. Telemetrie, Audit, Identität und Einstellungen gehen nur an die Ziele, die Sie konfigurieren.
• Host-Prozess-Verkehr: Der Host-Prozess ist die Claude Code CLI. claude gateway läuft unter den gleichen Third-Party-Regeln wie Amazon Bedrock und Google Cloud’s Agent Platform-Bereitstellungen und sendet nichts an Anthropic. Vor v2.1.227 sendete der Host-Prozess Startup-Telemetrie wie Produktversion und Plattform, die das Setzen von CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 in der Container-Umgebung ausschaltete. Diese Releases sendeten auch eine HEAD-Anfrage beim Boot ohne Body oder Anmeldedaten an /api/hello auf https://api.anthropic.com oder auf ANTHROPIC_BASE_URL, wenn die Umgebung es setzte, es sei denn, die Umgebung setzte auch eine Proxy-Variable wie HTTPS_PROXY oder ein mTLS-Client-Zertifikat. Sie ignorierten die Antwort, daher blockierte das Blockieren dieser Anfrage an der Egress-Firewall das Gateway nicht.
• Client-Analytik: Die CLI deaktiviert ihre eigene Nutzungsanalytik und Fehlerberichterstattung, während sie bei einem Gateway angemeldet ist. Vor der ersten Anmeldung sendet die CLI immer noch Startup-Events an Anthropic, auch auf Maschinen, deren verwaltete Einstellungen Gateway-Anmeldung erzwingen. Um diese auch auszuschalten, liefern Sie DISABLE_TELEMETRY in den gleichen Client-seitigen verwalteten Einstellungen, die Gateway-Anmeldung erzwingen.
• Fehlerberichterstattung: Die CLI schaltet Fehlerberichterstattung aus, wenn ihre Modellanfragen zu einem anderen Endpoint als Anthropic’s First-Party-API gehen, wie Amazon Bedrock oder ein benutzerdefiniertes ANTHROPIC_BASE_URL.
• Client-Maschinen: Entwickler-CLIs senden immer noch WebFetch-Hostname-Prüfungen und Versions-Prüfungen an Anthropic, es sei denn, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 und skipWebFetchPreflight: true sind gesetzt. Siehe Datennutzung.
• Umfrage-Bewertungen: Während der Anmeldung bei einem Gateway deaktiviert die CLI den Anthropic-gebundenen Bewertungs-Upload zusammen mit den Analytik-Streams, daher sendet sie Bewertungen nicht an Anthropic.
• Transkript-Freigabe: Das Wählen von Ja auf einer Umfrage-Transkript-Freigabe-Aufforderung schreibt eine lokale Datei unter ~/.claude/feedback-bundles/ statt zu Anthropic hochzuladen.
• Client-Updates: Update-Prüfungen sind getrennt vom Gateway-Verkehr. Pinnen Sie Versionen durch Ihre eigene Verteilung und setzen Sie DISABLE_UPDATES, wenn Laptops keine Releases abrufen dürfen. DISABLE_AUTOUPDATER stoppt nur Hintergrund-Updates, während claude update immer noch funktioniert.
• TLS: Bedienen Sie public_url über HTTPS in der Produktion, entweder vom Gateway-eigenen Listener über listen.tls oder von einem TLS-terminierenden Ingress vor einfachen HTTP-Replikationen mit listen.public_url gesetzt. Das Gateway weigert sich nicht, einfaches HTTP. Der IdP muss HTTPS in der Produktion bedienen, und Postgres unterstützt ?sslmode=require. Setzen Sie Strict-Transport-Security bei Ihrem Ingress.
• Vulnerability-Offenlegung: Folgen Sie Sicherheitsprobleme melden

​

Fehlerbehebung

• Gateway-Problem: Das Gateway-Stderr für das relevante Fenster, Ihre gateway.yaml mit Geheimnissen redigiert, die Gateway-Version, auf der Landingpage unter / und im x-cc-gateway-version-Response-Header auf /managed/settings angezeigt, und was sich kürzlich geändert hat
• Anmeldungs-Problem: Der Entwickler führt claude --debug-file ./claude-debug.txt aus, reproduziert und sendet diese Datei plus das Gateway-Audit-Protokoll für dasselbe Fenster
• Inferenz-Problem: Das angeforderte Modell, die konfigurierten Upstreams und das Gateway-Audit-Protokoll für die Anfrage, das aufzeichnet, welcher Upstream sie bedient hat und den Response-Status

​

Verwandt

• Claude-Apps-Gateway-Übersicht: Schnellstart und Entwickler-Verbindung
• Konfigurationsreferenz: Jede gateway.yaml-Option