Déploiement et exploitation de la passerelle Claude apps

1. Configurer votre fournisseur d’identité : enregistrez le client OAuth et consultez les notes spécifiques à chaque IdP pour Okta, Entra et Google
2. Déployer la passerelle : créez une image de conteneur épinglée et exécutez-la sur Kubernetes, Cloud Run ou votre propre plateforme. Cette section couvre également les décisions concernant les coûts, le contournement, les passerelles multiples et les environnements sans serveur
3. Configurer les opérations : journaux, sondes de santé, comportement en cas de panne, rotation des secrets et mises à jour. Référence pour le moment où vous configurez la surveillance et les runbooks
4. Examiner la posture de sécurité : où les données circulent, le modèle de menace et les réponses de conformité. Référence pour un examen de sécurité

​

Configuration du fournisseur d’identité

• Servir /.well-known/openid-configuration, via HTTPS en production ; la passerelle accepte un émetteur http://, et un émetteur de bouclage local nécessite en outre CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
• Supporter le flux de code d’autorisation. PKCE (Proof Key for Code Exchange) est activé par défaut ; désactivez-le avec oidc.use_pkce: false pour les IdP qui ne le supportent pas
• Retourner email et optionnellement groups dans l’id_token, ou les servir à partir du point de terminaison userinfo avec oidc.userinfo_fallback: true

• Okta : le serveur d’autorisation de l’organisation à https://example.okta.com retourne un id_token mince qui omet email et groups, donc définissez oidc.userinfo_fallback: true chaque fois que vous l’utilisez comme issuer. Un serveur d’autorisation personnalisé tel que https://example.okta.com/oauth2/default qui inclut email et optionnellement groups dans l’id_token les émet directement et n’a besoin d’aucun fallback. Okta émet groups uniquement lorsque la portée groups est demandée dans oidc.scopes et que le filtre de revendication de groupes de l’application le permet ; userinfo_fallback ne peut pas remplir une revendication pour laquelle l’IdP n’a pas été interrogé.
• Microsoft Entra ID : issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra émet des ID d’objet de groupe plutôt que des noms, donc utilisez les GUID dans managed.policies.match.groups, ou utilisez les rôles d’application pour des noms lisibles par l’homme. Si votre locataire émet des rôles sous roles au lieu de groups, définissez oidc.groups_claim: roles.
• Google Workspace : issuer = https://accounts.google.com. L’id_token de Google ne porte pas de groupes. Pour utiliser allowed_groups basé sur les groupes ou managed.policies avec Google comme IdP, configurez oidc.google_groups, qui recherche les groupes de chaque utilisateur via l’API Directory du SDK Admin en utilisant un compte de service avec délégation au niveau du domaine. Sans cela, utilisez oidc.allowed_email_domains pour le contrôle d’accès à l’adhésion et managed.policies.match.email_domain pour l’attribution de politique. Google ignore également la portée standard offline_access. Pour les jetons d’actualisation, définissez oidc.scopes: [openid, profile, email] et oidc.extra_auth_params: { access_type: offline, prompt: consent }.

​

Déploiement

• Coûts : pas de licence séparée ou de frais par siège. La passerelle fait partie du binaire claude, donc vous payez l’inférence via votre engagement existant, plus le calcul qu’elle exécute.
• Contournement : la passerelle n’impose pas que la seule route vers un modèle passe par elle. Un développeur avec sa propre credential peut toujours appeler le fournisseur directement, donc fermer ce chemin est une décision de politique réseau, par exemple bloquer la sortie vers api.anthropic.com sauf depuis la passerelle. Bloquer cette sortie casse également la vérification de sécurité du domaine WebFetch, qui appelle api.anthropic.com depuis la machine de chaque développeur. Définissez skipWebFetchPreflight: true dans la politique gérée pour la désactiver.
• Passerelles multiples : chaque est un déploiement séparé avec sa propre configuration, et le CLI stocke la confiance et les credentials par nom d’hôte de passerelle, donc les équipes peuvent utiliser différentes passerelles sans conflit. Pour servir plusieurs émetteurs OIDC, exécutez des instances séparées.
• Sans serveur : Cloud Run fonctionne si vous définissez min-instances: 1 pour éviter la découverte OIDC à froid. Lambda et Cloud Functions ne fonctionnent pas, car la passerelle est un serveur HTTP de longue durée.

• Sur chaque amont sauf provider: anthropic, la passerelle écrit un ping SSE une fois qu’un flux a été silencieux pendant environ 15 secondes.
• Sur provider: anthropic, la passerelle transmet la réponse inchangée, y compris les propres pings de l’API Anthropic.

​

Image de conteneur

1. Téléchargez la version Linux pour l’architecture de votre image à partir d’une version épinglée ; consultez Installer une version spécifique pour l’URL de téléchargement.
2. Vérifiez-la par rapport au manifest.json signé GPG de la version comme décrit dans Intégrité binaire et signature de code.
3. Copiez-la dans le contexte de construction.

• Une image basée sur glibc : la seule dépendance dynamique de la version glibc est les bibliothèques glibc. Les images basées sur Musl ont besoin de la version linux-x64-musl ou linux-arm64-musl plus des packages supplémentaires ; consultez Configuration Alpine Linux.
• Un répertoire d’état inscriptible : la passerelle s’exécute en tant qu’utilisateur quelconque, mais les images minimales n’ont pas de répertoire personnel inscriptible. Définissez CLAUDE_CONFIG_DIR sur un chemin inscriptible tel que /tmp/.claude.
• La commande du conteneur : claude gateway --config /etc/claude/gateway.yaml, avec le fichier de configuration monté en lecture seule et les secrets fournis en tant que variables d’environnement ; la passerelle écoute sur listen.port, par défaut 8080.

​

Kubernetes

• Montez la configuration à partir d’une ConfigMap et les secrets à partir d’un Secret ; référencez les secrets dans le YAML via ${file:/path/to/secret} ou en tant que variables d’environnement
• Terminez TLS à l’Ingress et définissez listen.public_url sur le nom d’hôte de l’Ingress
• Pointez la sonde de disponibilité sur GET /readyz et la sonde de vivacité sur GET /healthz

​

Cloud Run

• Laissez listen.port à sa valeur par défaut de 8080, qui correspond au PORT par défaut de Cloud Run, ou définissez port: ${PORT}
• Définissez public_url sur l’origine accessible de l’extérieur. Pour la production, c’est normalement le nom d’hôte d’un équilibreur de charge interne, car /login rejette les adresses publiques et l’URL *.run.app se résout en une, donc l’URL Cloud Run seule fonctionne uniquement pour un test de fumée curl ou navigateur. L’exception est un réseau où *.run.app se résout en privé via Private Service Connect et une zone privée Cloud DNS ; dans cette topologie l’URL Cloud Run est un public_url valide. L’exemple travaillé Google Cloud couvre les deux.
• Montez la configuration en tant que volume secret
• Définissez min-instances: 1 pour éviter une découverte OIDC à froid à la première demande

​

Envoyer l’URL de la passerelle aux machines des développeurs

​

Déploiements à grande échelle

• La passerelle ne peut pas voir au-delà de votre équilibreur de charge. Sans listen.trusted_proxies, chaque développeur semble provenir de l’adresse de l’équilibreur de charge et partage une limite. Définissez-le avant toute autre chose. La passerelle enregistre un avertissement la première fois qu’elle ignore un en-tête X-Forwarded-For.
• De nombreux développeurs partagent quelques adresses de sortie NAT ou VPN. Ils partagent les limites de ces adresses même lorsque trusted_proxies est correct. Augmentez rate_limits pour l’adapter.

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

​

Opérations

​

Journaux

• Événements d’audit : JSON sur une seule ligne par événement pertinent pour la sécurité. Canalisez stderr vers votre agrégateur de journaux. Les événements émis incluent 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 et admin.limit.delete. Les champs varient selon l’événement :
  • Les événements de mint et refresh réussis portent sub, email, client_ip et le résultat
  • auth.denied et access.denied portent la raison et l’adresse IP du client, plus le chemin de la demande pour auth.denied, car aucune identité utilisateur n’existe à ces refus. Deux raisons access.denied changent ce que l’événement porte :
    • xff_unparseable : l’événement porte également l’entrée X-Forwarded-For qui n’a pas pu être lue
    • client_ip_unknown : l’événement ne porte pas d’adresse IP client, car la connexion n’avait pas d’adresse de pair tandis qu’une liste access_control était définie
  • access.public_client porte l’adresse IP du client de la première demande par processus à arriver d’une adresse publique tandis que access_control.allow_cidrs est vide. La passerelle sert la demande comme d’habitude ; l’événement signale que la passerelle peut être accessible depuis l’internet public. Consultez la référence access_control pour ce qui compte comme public et pour la liste d’autorisation recommandée.
  • inference enregistre quel amont a servi la demande et le statut de la réponse
  • desktop_bootstrap.denied enregistre une récupération de bootstrap Claude Desktop rejetée avec la raison (not_configured, policy_not_opted_in ou no_policy_matched) et l’identité de l’utilisateur
  • admin.denied enregistre une tentative d’authentification d’API admin rejetée avec l’adresse IP du client, la méthode, le chemin et une raison, sans le matériel de clé présenté : invalid_key quand une x-api-key a été présentée mais ne correspondait à aucune clé configurée, bearer_rejected quand seul un en-tête Authorization a été présenté et il n’a pas vérifié comme une session de passerelle dans admin.admin_groups, ou no_credentials quand aucun en-tête n’a été présenté
• Journaux opérationnels : lignes lisibles par l’homme avec préfixe [gateway] pour le démarrage, les avertissements et les erreurs en amont. La variable d’environnement CLAUDE_GATEWAY_LOG_LEVEL contrôle la verbosité et accepte debug, info, warn ou error, avec info par défaut. À debug, chaque connexion et actualisation enregistre également les noms, pas les valeurs, des revendications dans l’id_token, plus les noms des revendications userinfo quand userinfo_fallback en a fourni, afin que vous puissiez diagnostiquer les paramètres email_claim et groups_claim sans enregistrer les PII. Cela n’affecte pas les événements d’audit, qui sont toujours émis.

​

Santé

​

Demandes en amont concurrentes

• Ajouter des répliques.
• Augmenter la limite sur chaque réplique. Définissez la variable d’environnement BUN_CONFIG_MAX_HTTP_REQUESTS sur le conteneur de passerelle à un nombre entier de 1 à 65535, puis redémarrez le conteneur.

​

Comportement en cas de panne

• Sessions existantes : les jetons porteurs valident localement avec le secret JWT, les actualisations de session ne touchent pas le magasin, et le processus de passerelle peut toujours servir l’inférence
• Nouvelles connexions : échouent jusqu’à la récupération de Postgres, car le flux d’appareil et ses compteurs de limite de débit vivent dans Postgres
• Application des limites de dépenses : échoue ouvert par défaut pendant la panne, donc l’inférence continue de circuler ; basculez-la pour échouer fermé si vous préférez bloquer plutôt que de fonctionner sans compteur
• Disponibilité : par défaut /readyz signale non-prêt dès que Postgres est inaccessible, donc chaque réplique échoue sa vérification de disponibilité à la fois. Là où le trafic ne atteint que les répliques qui passent la vérification, tout le trafic, y compris l’inférence que la passerelle pourrait toujours servir, échoue jusqu’à la récupération de Postgres. La sonde de vivacité sur /healthz continue de passer tout au long.

​

Période de grâce de disponibilité

​

Rotation du secret JWT

1. Générez un nouveau secret. Ajoutez-le au début du tableau session.jwt_secret.
2. Déployez le déploiement. Les nouveaux jetons signent avec le nouveau secret ; les anciens jetons valident toujours.
3. Après ttl_hours plus une marge, supprimez l’ancien secret et déployez à nouveau.

​

Postgres

​

Mises à jour

• La fenêtre de drainage : définissez la variable d’environnement CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS sur le conteneur de passerelle à un nombre entier positif de millisecondes, tel que 120000. La passerelle ignore une valeur sous toute autre forme, telle que 120s, et conserve la valeur par défaut de 25 secondes
• La période de grâce de votre orchestrateur : terminationGracePeriodSeconds sur Kubernetes, ou stopTimeout sur Amazon ECS

• Amazon ECS sur Fargate : stopTimeout permet au maximum 120 secondes
• Cloud Run : arrête une instance 10 secondes après SIGTERM, donc les flux ouverts obtiennent au maximum 10 secondes là, quelle que soit la fenêtre de drainage

​

Sécurité

​

Flux de données

​

Résumé du modèle de menace

• Les développeurs détiennent des JWT de courte durée au lieu de clés en amont brutes. La jambe CLI-à-passerelle utilise la subvention d’appareil RFC 8628, et l’échange de code d’autorisation de la passerelle avec l’IdP exécute PKCE dans la configuration par défaut, donc un code d’autorisation IdP intercepté est inutile.
• La page de vérification d’appareil applique POST de même origine et une limite de débit par IP par RFC 8628 §5.1. Consultez Résistance à la force brute du code utilisateur.
• Les demandes de la passerelle à votre IdP, vos collecteurs OTLP, et les amonts provider: anthropic passent par une protection contre la falsification de demande côté serveur (SSRF) qui résout DNS, bloque les adresses de lien local et de métadonnées cloud plus la bouclage par défaut, et épingle la connexion à l’IP résolue, donc les URL influencées par l’opérateur ne peuvent pas être redirigées vers les points de terminaison de métadonnées cloud. Les plages privées RFC 1918 sont délibérément autorisées, car les IdP et les collecteurs OTLP vivent couramment sur des adresses IP privées. Pour les autres fournisseurs, la passerelle refuse une base_url qui nomme l’une de ces adresses ou un nom d’hôte de métadonnées lorsqu’elle charge la config, et le SDK du fournisseur se connecte ensuite sans la vérification DNS. Si vous activez sortie proxy uniquement, cette vérification d’adresse se déplace vers votre proxy avant : la passerelle lui transmet les noms d’hôte et la liste d’autorisation du proxy doit refuser ces destinations. Définissez CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 dans l’environnement de la passerelle uniquement lorsque quelque chose que la passerelle doit atteindre légitimement vit sur la bouclage, comme un IdP de développement local ou un collecteur OTLP sidecar sur localhost. La variable assouplit le bloc de bouclage pour chaque URL configurée par l’opérateur et ignore également l’avertissement au démarrage qui vérifie si le pod peut atteindre le point de terminaison de métadonnées cloud, donc préférez donner au collecteur sa propre adresse interne.

• Un hôte de passerelle compromis : l’hôte détient à la fois la credential en amont et distribue les paramètres gérés à chaque développeur connecté, donc le contrôle de la configuration de la passerelle est comparable au contrôle de votre MDM. La boîte de dialogue d’approbation du CLI pour les paramètres capables de shell limite les changements silencieux mais ne remplace pas la sécurité de l’hôte.
• Un fournisseur OIDC malveillant : le fournisseur signe les id_tokens que la passerelle fait confiance, donc il peut affirmer n’importe quelle identité. L’examen et la sécurisation de votre IdP sont votre responsabilité.

​

Résistance à la force brute du code utilisateur

​

Posture de conformité

• Résidence des données : le plan de données de la passerelle elle-même n’envoie rien à Anthropic sauf si l’API Anthropic est un amont configuré ; lorsqu’elle l’est, votre accord de traitement des données existant s’applique au chemin d’inférence. La télémétrie, l’audit, l’identité et les paramètres vont uniquement aux destinations que vous configurez.
• Trafic du processus hôte : le processus hôte est le CLI Claude Code. La commande claude gateway s’exécute selon les mêmes règles tierces que les déploiements Amazon Bedrock et Google Cloud Agent Platform et n’envoie rien à Anthropic. Avant la v2.1.227, le processus hôte envoyait la télémétrie de démarrage telle que la version du produit et la plateforme, que le paramètre CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 dans l’environnement du conteneur désactivait. Ces versions envoyaient également une demande HEAD au démarrage, sans corps ni credentials, à /api/hello sur https://api.anthropic.com, ou sur ANTHROPIC_BASE_URL lorsque l’environnement l’a défini, sauf si l’environnement a également défini une variable proxy telle que HTTPS_PROXY ou un certificat client mTLS. Elles ignoraient la réponse, donc bloquer cette demande au pare-feu de sortie n’affectait pas la passerelle.
• Analytique client : le CLI désactive sa propre analytique d’utilisation et le rapport d’erreurs lorsqu’il est connecté à une passerelle. Avant la première connexion, le CLI envoie toujours les événements de démarrage à Anthropic, y compris sur les machines dont les paramètres gérés forcent la connexion à la passerelle. Pour les désactiver aussi, livrez DISABLE_TELEMETRY dans les mêmes paramètres gérés côté client qui forcent la connexion à la passerelle.
• Rapport d’erreurs : le CLI désactive le rapport d’erreurs chaque fois que ses demandes de modèle vont à n’importe quel point de terminaison autre que l’API première partie d’Anthropic, comme Amazon Bedrock ou un ANTHROPIC_BASE_URL personnalisé.
• Machines client : les CLI des développeurs envoient toujours les vérifications de nom d’hôte WebFetch et les vérifications de version à Anthropic sauf si CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 et skipWebFetchPreflight: true sont définis. Consultez utilisation des données.
• Évaluations d’enquête : lorsqu’il est connecté à une passerelle, le CLI désactive le téléchargement d’évaluation lié à Anthropic ainsi que les flux d’analytique, donc il n’envoie pas les évaluations à Anthropic.
• Partage de transcription : choisir Oui sur une invite de partage de transcription d’enquête écrit un fichier local sous ~/.claude/feedback-bundles/ au lieu de télécharger vers Anthropic.
• Mises à jour client : les vérifications de mise à jour sont séparées du trafic de passerelle. Épinglez les versions via votre propre distribution et définissez DISABLE_UPDATES si les ordinateurs portables ne doivent pas récupérer les versions. DISABLE_AUTOUPDATER arrête uniquement les mises à jour en arrière-plan tandis que claude update fonctionne toujours.
• TLS : servez public_url via HTTPS en production, soit à partir du propre écouteur de la passerelle via listen.tls, soit à partir d’une ingress terminant TLS devant les répliques HTTP simples, avec listen.public_url défini dans les deux cas. La passerelle ne refuse pas HTTP simple. L’IdP doit servir HTTPS en production, et Postgres supporte ?sslmode=require. Définissez Strict-Transport-Security à votre ingress.
• Divulgation de vulnérabilité : suivez Signaler les problèmes de sécurité

​

Dépannage

• Problème de passerelle : la sortie d’erreur de la passerelle pour la fenêtre pertinente, votre gateway.yaml avec les secrets masqués, la version de la passerelle, affichée sur la page d’accueil à / et dans l’en-tête de réponse x-cc-gateway-version sur /managed/settings, et ce qui a changé récemment
• Problème de connexion : le développeur exécute claude --debug-file ./claude-debug.txt, reproduit le problème, et envoie ce fichier plus le journal d’audit de la passerelle pour la même fenêtre
• Problème d’inférence : le modèle demandé, les upstreams configurés, et le journal d’audit de la passerelle pour la demande, qui enregistre quel upstream l’a servie et le statut de la réponse

​

Connexes

• Aperçu de la passerelle Claude apps : démarrage rapide et connexion des développeurs
• Référence de configuration : chaque option du fichier gateway.yaml