Déploiement et exploitation de la passerelle Claude apps

Cette page couvre l’aspect opérationnel de l’exécution de la passerelle Claude apps : enregistrement d’un client OAuth auprès de votre fournisseur d’identité (IdP), déploiement de la passerelle en tant que conteneur, et son exploitation au quotidien. Pour chaque option du fichier gateway.yaml que la passerelle lit au démarrage, consultez la Référence de configuration. Un déploiement en production suit quatre étapes dans l’ordre, et les sections ci-dessous les correspondent. Les deux premières sont des choix à faire ; les deux dernières sont des documents de référence à consulter une fois qu’elle est en cours d’exécution.

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é

Si une connexion ou un démarrage échoue en cours de route, allez directement à Dépannage, qui est indexé sur l’erreur que vous voyez.

​

Configuration du fournisseur d’identité

Enregistrez une application web OAuth/OpenID Connect (OIDC) confidentielle auprès d’un seul URI de redirection, https://<gateway>/oauth/callback, et assignez-la aux utilisateurs ou groupes qui doivent avoir accès à la passerelle. Tout IdP conforme à OIDC fonctionne : Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate et autres. L’IdP doit répondre à trois exigences :

• 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

Pour l’infrastructure à clé publique privée, définissez oidc.ca_cert_pem. Quelques fournisseurs gèrent les revendications d’email et de groupe différemment :

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

Pour obtenir de l’aide auprès d’un fournisseur d’identité non couvert ci-dessus, consultez Dépannage.

​

Déploiement

La passerelle est un seul binaire Linux. Elle se met à l’échelle horizontalement car les répliques sont sans état et Postgres est la couche de coordination partagée. Exécutez-la comme vous exécutez les services sans état dans votre environnement. Le reste de cette section indique ce dont l’image a besoin, avec de brèves notes pour Kubernetes et Cloud Run. La passerelle est conçue pour s’exécuter à l’intérieur de votre réseau, car elle détient votre credential en amont et agit comme le seul point de sortie pour l’inférence. Elle peut s’exécuter n’importe où vos développeurs et votre IdP peuvent atteindre via HTTPS ; traitez-la comme tout autre service détenant une credential de production. Quelques décisions façonnent le déploiement au-delà de l’endroit où il s’exécute :

• Coûts : il n’y a pas de licence séparée ou de frais par siège pour la passerelle ; elle fait partie du binaire claude. Vous payez l’inférence via votre engagement cloud ou Anthropic existant, plus le calcul pour le conteneur et votre collecteur de télémétrie.
• 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 passerelle est un déploiement séparé avec sa propre configuration. Le CLI stocke son empreinte de confiance et ses credentials par nom d’hôte de passerelle, donc différentes équipes peuvent se connecter à différentes passerelles sans conflit. Pour servir plusieurs émetteurs OIDC, exécutez des instances séparées.
• Sans serveur : Cloud Run fonctionne ; 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.

Chaque topologie de production ici place un proxy L7, tel qu’une Ingress, le front-end de Cloud Run ou un ALB, devant les répliques HTTP simples. Définissez listen.trusted_proxies sur les plages sources du proxy afin que la passerelle lise les adresses IP des clients à partir de X-Forwarded-For. La passerelle honore l’en-tête uniquement lorsque le pair TCP est de confiance ; l’exemple travaillé Google Cloud a des valeurs concrètes par topologie. Sans proxies de confiance, chaque demande semble provenir de l’adresse IP du proxy, ce qui réduit les limites de débit par IP en un seul compartiment partagé et enregistre l’adresse IP du proxy dans les événements d’audit.

​

Image de conteneur

Créez votre propre image autour du binaire claude natif de la version standard de Claude Code :

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.

Miroitez la version dans votre registre interne si vos constructions ne peuvent pas atteindre l’hôte de version, et épinglez la version que votre flotte exécute. Au-delà du binaire, l’image a besoin de :

• 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

Exécutez la passerelle en tant que Deployment, comme tout service sans état :

• 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

Configurez le service comme suit :

• 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

Une fois que la passerelle est en service, envoyez forceLoginMethod et forceLoginGatewayUrl à la machine de chaque développeur via les paramètres gérés, via MDM ou en écrivant directement le fichier managed-settings.json par système d’exploitation. Sans cela, /login affiche le sélecteur de compte standard sans option de passerelle. Consultez Paramètres gérés côté client pour les chemins de fichiers.

​

Opérations

Une fois que la passerelle traite le trafic, l’exploitation au quotidien consiste à lire ses journaux, à sonder sa santé et à faire tourner ses secrets selon votre calendrier. Les sous-sections couvrent chacun, plus ce que Postgres détient et comment les mises à jour et les restaurations se comportent.

​

Journaux

La passerelle écrit deux flux sur stderr, tous deux JSON-friendly :

• É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, auth.denied, access.denied, inference, managed.serve, spend.blocked et admin.denied. 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
  • Les événements de refus portent la raison, le chemin et l’adresse IP du client, car aucune identité n’existe au refus
  • inference enregistre quel amont a servi la demande et le statut de la réponse
  • admin.denied enregistre une tentative d’authentification d’API admin rejetée avec la raison (invalid_key ou no_credentials), l’adresse IP du client, la méthode et le chemin, sans le matériel de clé 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 info, warn ou error, avec info par défaut. Elle n’affecte pas les événements d’audit, qui sont toujours émis.

​

Santé

La passerelle sert GET /healthz comme sonde de vivacité et GET /readyz comme sonde de disponibilité ; /readyz vérifie que le magasin est accessible. Les deux sont exempts de access_control.allow_cidrs, donc les sondes continuent de fonctionner sur un écouteur verrouillé. Le document de découverte OAuth à /.well-known/oauth-authorization-server retourne également 200 uniquement après le chargement de la configuration, la découverte OIDC, la construction du client en amont et la migration Postgres réussissent, donc il double comme vérification de démarrage de bout en bout. Une passerelle en cours d’exécution sert également une description des chemins et des formes de demande qu’elle accepte à <public_url>/protocol, correspondant à la version que vous exécutez. Le contenu n’est pas stable entre les versions.

​

Comportement en cas de panne

Si Postgres tombe en panne, la passerelle elle-même continue de servir les développeurs connectés et les nouvelles connexions échouent. Que les développeurs continuent réellement à travailler dépend de la façon dont votre orchestrateur gère la disponibilité :

• 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é : /readyz signale non-prêt pendant la panne, donc les orchestrateurs qui contrôlent le trafic sur la disponibilité retirent chaque réplique de la rotation à la fois. Dans cette topologie tout le trafic, y compris l’inférence que la passerelle pourrait toujours servir, échoue à l’équilibreur de charge jusqu’à la récupération de Postgres. La sonde de vivacité sur /healthz continue de passer, donc les répliques ne sont pas redémarrées. Pointez la sonde de disponibilité sur /healthz à la place si vous préférez que les développeurs connectés continuent de travailler pendant une panne du magasin ; le coût est que les nouvelles connexions échouent contre une réplique qui signale toujours prête.

Si votre IdP tombe en panne, les sessions existantes fonctionnent jusqu’à ttl_hours, et les nouvelles connexions et actualisations échouent. Définissez un ttl_hours plus long si votre IdP a des fenêtres de maintenance fréquentes.

​

Rotation du secret JWT

Faites tourner le secret de signature en trois étapes afin que les sessions existantes restent valides :

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.

La rotation est également le seul moyen de forcer les sessions à sortir avant leur expiration : les jetons porteurs valident localement par rapport au secret JWT, donc il n’y a pas de révocation par session. Remplacer le secret directement, sans conserver l’ancien dans le tableau, invalide chaque session en attente à la fois. Pour le déprovisionnement individuel, déprovisionner l’utilisateur dans votre IdP ; sa session se termine dans ttl_hours.

​

Postgres

La passerelle détient cinq tables, toutes créées par ses migrations au démarrage : Une boucle de 30 secondes expire les lignes kv au-delà de leur TTL, et un balayage horaire applique les fenêtres de rétention sur les tables de dépenses, donc rien ne croît sans limite. Sans limites de dépenses configurées, seul kv est écrit. Si votre politique de sécurité interdit DDL du rôle d’application, pré-créez ces tables et _migrations avec un rôle admin et accordez au rôle d’application SELECT, INSERT, UPDATE, DELETE sur chacun. Avec les limites de dépenses en usage, une base de données perdue signifie le suivi des dépenses et les plafonds perdus, pas seulement les re-connexions des développeurs, donc exécutez des sauvegardes régulières. Pour effacer immédiatement un développeur parti plutôt que d’attendre la rétention, exécutez DELETE FROM principal_emails WHERE principal = '<sub>' directement ; cela supprime la seule table contenant son email, son nom et ses groupes. Les lignes spend et admin_audit ne référencent que le sub OIDC pseudonyme.

​

Mises à jour

Les répliques sont sans état, donc un redémarrage roulant est sûr à tout moment. La passerelle exécute les migrations de schéma au démarrage, ce qui signifie que le déploiement du nouveau binaire auto-migre la base de données. Si le rôle de base de données ne peut pas exécuter DDL, pré-créez le schéma, y compris la table _migrations amorcée à la version actuelle ; sinon le démarrage échoue en tentant CREATE TABLE. Les migrations sont en ajout seul, donc revenir à un binaire antérieur qui connaît moins de migrations est sûr ; il ignore les lignes supplémentaires. La restauration re-valide également le YAML par rapport au schéma du binaire plus ancien, donc une configuration qui a adopté une clé introduite par la version plus récente échoue au démarrage sur l’ancienne. Supprimez la nouvelle clé avant de revenir. Parce que vous épinglez la version de la passerelle dans votre propre image, les correctifs dans les nouvelles versions de Claude Code, y compris les correctifs de sécurité, atteignent votre déploiement uniquement lorsque vous mettez à jour l’épingle et redéployez. Incluez la passerelle dans le même calendrier de correction que vous utilisez pour les autres services qui détiennent des credentials de production.

​

Sécurité

Cette section répond aux questions qu’un examen de sécurité pose : quelles données circulent à travers la passerelle et où elles vont, quelles attaques la conception défend, et quelles réponses appartiennent à un questionnaire de conformité.

​

Flux de données

​

Résumé du modèle de menace

La passerelle se trouve à l’intérieur de votre périmètre réseau, mais les ordinateurs portables des développeurs individuels ne sont pas traités comme de confiance. La conception en tient compte de trois façons :

• 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 sortantes 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 telles que l’IdP et les destinations OTLP 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 le développement local par rapport à un IdP ou collecteur de bouclage, définissez CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 dans l’environnement de la passerelle ; laissez-le non défini en production.

Si vous ajoutez vos propres contrôles de sortie, la passerelle doit atteindre le serveur de métadonnées chaque fois qu’elle utilise des credentials de métadonnées d’instance tels que l’identité de charge de travail. Deux menaces sont hors de portée car c’est votre infrastructure à sécuriser :

• 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 unique 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

Le user_code qu’un développeur tape dans la page de vérification /device est 8 caractères tirés d’un alphabet de 20 caractères, ce qui donne 20⁸ ou environ 2,56×10¹⁰ combinaisons, et il expire après 10 minutes. La passerelle applique des limites de débit par IP sur les points de terminaison de subvention d’appareil, configurables via rate_limits. Augmentez les limites si de nombreux développeurs se connectent à partir d’une seule adresse NAT d’entreprise partagée. Les limites s’appliquent uniquement au flux de connexion, pas à l’inférence.

​

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, qui peut envoyer l’analytique de démarrage et les vérifications de mise à jour à Anthropic. Pour les déploiements à sortie stricte, définissez CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 dans l’environnement du conteneur de la passerelle.
• Analytique client : le CLI désactive sa propre analytique d’utilisation lorsqu’il est connecté à une passerelle, et le rapport d’erreurs est désactivé par défaut sur les surfaces d’API tierces.
• 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 : la credential de passerelle désactive le puits d’évaluation lié à Anthropic, donc les évaluations ne sont pas envoyées à 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. 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

Pour les questions et les commentaires, utilisez Support Claude Code, ou ouvrez un problème sur le référentiel GitHub Claude Code. Lors de la signalisation d’un problème, incluez :

• Problème de passerelle : le stderr 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 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 amonts configurés et le journal d’audit de la passerelle pour la demande, qui enregistre quel amont l’a servie et le statut de la réponse

La sortie d’erreur standard de la passerelle inclut le flux d’événements d’audit, le journal d’audit enregistre les identités des développeurs, et le fichier de débogage enregistre la sortie des hooks et du serveur MCP de la machine du développeur. Examinez et masquez ces informations avant de les publier sur un problème public.

​

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