> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Déploiement et exploitation de la passerelle Claude apps > Enregistrez la passerelle auprès de votre fournisseur d'identité, créez le conteneur, déployez sur Kubernetes ou Cloud Run, et exploitez-la : vérifications de santé, rotation des secrets, mises à jour et sécurité. Cette page couvre l'aspect opérationnel de l'exécution de la [passerelle Claude apps](/fr/claude-apps-gateway) : 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](/fr/claude-apps-gateway-config). 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é](#identity-provider-setup) : enregistrez le client OAuth et consultez les notes spécifiques à chaque IdP pour Okta, Entra et Google 2. [Déployer la passerelle](#deployment) : 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](#operations) : 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é](#security) : 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](#troubleshooting), qui est indexé sur l'erreur que vous voyez. **Déployez sur votre réseau privé.** Claude Code ne se connecte qu'à une passerelle dont l'adresse est privée. C'est une protection de sécurité, car une passerelle de confiance peut envoyer des paramètres qui exécutent des commandes sur les machines des développeurs. Placez la passerelle derrière un équilibreur de charge interne ou un VPN et donnez-lui un nom d'hôte qui se résout uniquement en adresses IP privées.

Configuration du fournisseur d'identité

Enregistrez une application web OAuth/OpenID Connect (OIDC) confidentielle auprès d'un seul URI de redirection, `https:///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://`](/fr/claude-apps-gateway-config#oidc), 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//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`](/fr/claude-apps-gateway-config#oidc), 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](#troubleshooting). Les jetons d'actualisation permettent à la passerelle de renouveler la session d'un développeur silencieusement, sans renvoyer le développeur au navigateur. Ils pilotent également le déprovisionnement, car lorsque l'IdP désactive un utilisateur, l'actualisation suivante échoue et la session se termine dans `ttl_hours`. La passerelle demande `offline_access` par défaut pour obtenir un jeton d'actualisation. Si votre IdP nécessite un consentement explicite pour l'accès hors ligne, configurez le client OAuth pour l'autoriser. Si votre IdP ne peut pas du tout émettre de jetons d'actualisation, la passerelle fonctionne toujours, mais il n'y a pas de renouvellement silencieux, donc les développeurs réexécutent la connexion au navigateur lorsque leur session expire. Pour éviter que cela ne se produise toutes les heures, augmentez [`session.ttl_hours`](/fr/claude-apps-gateway-config#session) à `8` ou `12`. Le compromis est la latence de déprovisionnement, car sans jetons d'actualisation un utilisateur désactivé conserve l'accès jusqu'à l'expiration du TTL plus long.

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](/fr/data-usage#webfetch-domain-safety-check), 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`](/fr/claude-apps-gateway-config#listen) 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](/fr/claude-apps-gateway-on-gcp) 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](/fr/setup#install-a-specific-version) 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](/fr/setup#binary-integrity-and-code-signing). 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](/fr/setup#alpine-linux-and-musl-based-distributions). * **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` **Identité de charge de travail** Préférez l'identité de charge de travail de la plateforme aux clés statiques : IRSA sur EKS pour Bedrock, Workload Identity sur GKE pour Agent Platform, et identité de charge de travail sur AKS pour Foundry. Définissez `auth: {}` dans le bloc en amont, ou `use_azure_ad: true` pour Foundry, et la passerelle récupère l'identité du pod via la chaîne de credentials par défaut de ce fournisseur. Pour un appairage inter-cloud, tel qu'un amont Bedrock sur GKE, définissez des credentials explicites dans le bloc `auth` de l'amont à la place. La [référence `upstreams`](/fr/claude-apps-gateway-config#upstreams) a des détails de configuration par plateforme.

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](/fr/claude-apps-gateway#prerequisites) 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](/fr/claude-apps-gateway-on-gcp#deploy-the-gateway) 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 Pour un exemple travaillé complet sur Google Cloud, couvrant Cloud Run ou GKE, Cloud SQL et Secret Manager, consultez [Déployer sur Google Cloud](/fr/claude-apps-gateway-on-gcp).

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](/fr/claude-apps-gateway-config#client-side-managed-settings) 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 à `/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](/fr/claude-apps-gateway-spend-limits#postgres-availability)** : é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 : | Table | Contenu | Rétention | | ------------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `kv` | Subventions d'appareil (TTL de 10 minutes) et compteurs de limite de débit | TTL par ligne | | `spend` | Compteurs de dépenses période-à-date par principal, en cents | `admin.spend_retention_months`, par défaut 13 | | `spend_limits` | Plafonds de dépenses configurés | Jusqu'à suppression via l'API | | `admin_audit` | Piste de mutation de l'API admin | `admin.audit_retention_days`, par défaut 365 | | `principal_emails` | Email, nom d'affichage et groupes IdP de chaque principal vus en dernier. Contient des PII. | `admin.identity_retention_days` depuis la dernière activité, par défaut 90 | 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](/fr/claude-apps-gateway-spend-limits) 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 = ''` 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

| Données | Chemin | Envoyé à Anthropic par la passerelle | | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- | | Inférence (invites, complétions) | CLI → passerelle → votre amont | Uniquement si l'API Anthropic est un amont configuré | | Télémétrie (métriques OTLP, plus [journaux et traces opt-in](/fr/claude-apps-gateway-config#telemetry)) | CLI → passerelle → votre collecteur | Jamais | | Identité (email, groupes, sub) | IdP → passerelle → JWT → CLI ; le CLI l'estampille sur les exports OTLP | Jamais | | Paramètres gérés | Votre YAML de passerelle → CLI | Jamais | | Journal d'audit | Stderr de passerelle → votre agrégateur | Jamais |

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](#user-code-brute-force-resistance). * 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](/fr/claude-apps-gateway-config#managed) à 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`](/fr/claude-apps-gateway-config#http-tuning). 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](/fr/data-usage). * **É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é](/fr/security#reporting-security-issues)

Dépannage

Pour les questions et les commentaires, utilisez [Support Claude Code](https://support.claude.com/en/collections/14445694-claude-code), ou ouvrez un problème sur le [référentiel GitHub Claude Code](https://github.com/anthropics/claude-code/issues). 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 | Symptôme | Cause | Correctif | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Le `/login` d'un développeur affiche le sélecteur de compte standard au lieu de l'écran **Passerelle cloud** | `forceLoginMethod` ou `forceLoginGatewayUrl` n'est pas défini dans les paramètres gérés sur cette machine | Déployez le [fichier de paramètres gérés](/fr/claude-apps-gateway#set-the-gateway-url) sur l'appareil ; `/login` lit l'URL de la passerelle à partir de là | | Le démarrage affiche `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | La version de Claude Code installée est antérieure au support de la passerelle | Demandez au développeur de mettre à jour Claude Code vers une version qui inclut le support de la passerelle cloud | | CLI `/login` : `Gateway hosts must be on your organization's private network; resolves to the public (or unrecognized) address ` | Le nom d'hôte de la passerelle se résout en au moins une adresse IP publique. Claude Code vérifie chaque adresse résolue et exige que chacune soit privée. Une cause courante est un nom double pile où une famille se résout en une adresse publique, y compris les équilibreurs de charge double pile internes AWS, qui retournent des adresses AAAA de plage publique | Faites en sorte que le nom de la passerelle se résout uniquement en adresses privées sur les machines des développeurs. Pour un nom double pile, supprimez l'enregistrement de plage publique ou servez un nom DNS interne uniquement séparé. Consultez la [prérequis de réseau privé](/fr/claude-apps-gateway#prerequisites). | | CLI `/login` : `Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | Un `HTTPS_PROXY` ou `HTTP_PROXY` s'applique à l'hôte de la passerelle et le nom d'hôte du proxy se résout en une adresse publique. Un proxy dont l'hôte se résout uniquement en adresses privées est autorisé et ne déclenche pas cette erreur | Ajoutez l'hôte de la passerelle à `NO_PROXY` sur la machine du développeur afin que la connexion soit directe, ou utilisez un proxy dont le nom d'hôte se résout en adresses privées | | CLI `/login` : `Could not resolve gateway host ` | La machine ne peut pas résoudre le nom DNS interne de la passerelle, généralement parce qu'elle n'est pas sur le réseau d'entreprise | Demandez au développeur de se connecter à votre réseau ou VPN, puis réessayez `/login` | | Le démarrage se termine avec une erreur de validation de configuration nommant `store.postgres_url` | Aucun Postgres configuré ; la passerelle nécessite Postgres | Définissez `store.postgres_url`. Pour le développement local, utilisez un conteneur jetable : `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. | | Le démarrage se termine : `requires the native binary` | Exécution sous Node au lieu du binaire natif | Installez Claude Code avec l'une des [méthodes d'installation autonome](/fr/setup) | | Le démarrage se termine avec une erreur de découverte OIDC après `config.load` | `oidc.issuer` inaccessible, ou chaîne TLS non approuvée | Vérifiez que l'émetteur est accessible depuis le pod et sert `/.well-known/openid-configuration`. Définissez `ca_cert_pem` pour l'infrastructure à clé publique privée. | | Le démarrage se termine avec une erreur de permission Postgres | Le rôle d'application manque `CREATE TABLE` | Pré-créez le schéma avec un rôle admin et accordez DML au rôle d'application, ou accordez DDL temporairement pour les démarrages qui appliquent de nouvelles migrations | | `/oauth/callback` affiche « La connexion n'a pas pu être complétée » | Domaine de courrier rejeté, validation id\_token échouée, ou `email_verified` est explicitement `false`, que la passerelle rejette toujours sans remplacement | Vérifiez `allowed_email_domains` et que l'IdP retourne une revendication `email` vérifiée. Pour `email_verified: false`, corrigez la vérification côté IdP. Si votre IdP émet l'email sous un nom de revendication différent, définissez `oidc.email_claim`. | | Journal : `token exchange failed: id_token missing email claim` | L'IdP n'inclut pas `email` dans l'id\_token par défaut. Ce refus ne se déclenche que lorsque `allowed_email_domains` est défini ; sans cela, un email manquant frappe une session sans email | Configurez l'IdP pour émettre `email` dans l'id\_token. Okta : ajoutez `email` aux revendications de jeton ID d'un serveur d'autorisation personnalisé. Entra : ajoutez `email` comme revendication optionnelle sur l'enregistrement d'application. PingFederate : activez une politique OpenID Connect qui émet `email`. Si l'IdP sert `email` à partir du point de terminaison userinfo mais ne l'inclura pas dans l'id\_token, tel que le serveur d'autorisation de l'organisation Okta, définissez `oidc.userinfo_fallback: true`. | | Chaque demande Bedrock retourne 502 ; le journal affiche `Could not load credentials from any providers` | Sur EC2, la limite de saut par défaut d'IMDSv2 de 1 bloque la demande de métadonnées d'instance de l'intérieur du conteneur. Le démarrage et `/readyz` passent de toute façon car le SDK AWS résout les credentials d'instance à la première demande, pas à la construction du client | Augmentez la limite de saut avec `aws ec2 modify-instance-metadata-options --instance-id --http-put-response-hop-limit 2`, ou définissez-la dans le modèle de lancement. Le changement s'applique à chaque conteneur sur l'instance. Préférez les rôles de tâche ECS où disponibles, qui lisent les credentials à partir du point de terminaison des credentials du conteneur ECS et évitent complètement le changement, ou appliquez le changement sur une instance de passerelle dédiée pour limiter l'exposition. | | Erreur IdP : portée inconnue ou non supportée | L'IdP rejette les portées qu'il ne reconnaît pas | Définissez `oidc.scopes` exactement à la liste que votre IdP accepte ; elle doit inclure `openid`. La valeur par défaut est `openid profile email offline_access`. | | Les sessions ne se renouvellent pas silencieusement après la définition de `oidc.scopes` | `offline_access` a été supprimé de l'override | Rajoutez `offline_access` si votre IdP le supporte. Sans jeton d'actualisation, les développeurs réexécutent la connexion au navigateur tous les `session.ttl_hours`. | | Le navigateur affiche « Cette demande provenait d'un autre site et a été bloquée » | POST de formulaire inter-sites, bloqué comme protection CSRF. Attendu pour les pages intégrées ou proxifiées | Ouvrez le lien de vérification directement | | Chrome bloque le bouton Approuver avec « Refused to send form data … violates … Content Security Policy directive: form-action », mais la même page fonctionne dans Safari ou Firefox | Chrome applique `form-action` à toute la chaîne de redirection. Votre IdP redirige ensuite vers un deuxième hôte qui n'est pas sur la liste blanche. | Ajoutez chaque origine supplémentaire dans la chaîne de redirection à `oidc.form_action_origins`. Ouvrez Chrome DevTools → Console sur la page Approuver pour voir quelle origine a été bloquée. | | La connexion se termine à l'IdP mais le rappel échoue, avec une erreur CSP dans Chrome ou « ce lien de connexion a expiré » dans Safari | L'IdP a retourné le code via `response_mode=form_post`, qui l'auto-soumet inter-sites via POST à `/oauth/callback`. Chrome bloque cela sous une CSP stricte ; Safari autorise la soumission mais le rappel lit uniquement la chaîne de requête. | Assurez-vous que votre IdP honore `response_mode=query`, que la passerelle demande explicitement afin que le rappel soit une redirection simple | | La connexion fonctionne localement mais échoue derrière un ALB | `public_url` non défini, donc l'IdP obtient l'origine `http://` interne comme `redirect_uri` | Définissez `listen.public_url` sur l'origine `https://` externe | | Le développeur voit l'invite de confiance à plusieurs reprises | Le certificat TLS tourne par réplique ou par demande | Utilisez un certificat stable à l'ingress, ou terminez TLS une fois et exécutez les répliques via HTTP simple en interne | | CLI `/login` : « Could not verify the gateway's TLS certificate » ou `SELF_SIGNED_CERT_IN_CHAIN` | La chaîne TLS de la passerelle est signée par une CA privée non dans le magasin de confiance de l'hôte CLI | Claude Code lit le magasin de confiance du système d'exploitation par défaut sur le binaire natif et sur Node 22.15 ou ultérieur ; [`CLAUDE_CODE_CERT_STORE`](/fr/network-config#ca-certificate-store) contrôle ce comportement. Si la CA est installée dans le magasin de confiance du système d'exploitation, assurez-vous que les développeurs utilisent un runtime actuel. Sinon, définissez `NODE_EXTRA_CA_CERTS` sur le PEM du certificat CA avant de lancer. L'invite d'empreinte de première connexion s'applique toujours. | * [Aperçu de la passerelle Claude apps](/fr/claude-apps-gateway) : démarrage rapide et connexion des développeurs * [Référence de configuration](/fr/claude-apps-gateway-config) : chaque option du fichier `gateway.yaml`