32 32
33* [`admin`](#admin) : authentification de l'API Admin et rétention pour les limites de dépenses33* [`admin`](#admin) : authentification de l'API Admin et rétention pour les limites de dépenses
34* [`enforcement`](#enforcement) : comportement de limite de dépenses fail-open ou fail-closed34* [`enforcement`](#enforcement) : comportement de limite de dépenses fail-open ou fail-closed
35* [`pricing`](#pricing) : tarifs contractuels et multiplicateur de remise pour le compteur de dépenses35* [`pricing`](#pricing) : tarifs contractuels et multiplicateur de remise pour le compteur de dépenses et pour les chiffres de coût que les développeurs voient
36* [`models`](#models) et `auto_include_builtin_models` : liste de modèles curée par l'administrateur et IDs par upstream36* [`models`](#models) et `auto_include_builtin_models` : liste de modèles curée par l'administrateur et IDs par upstream
37* [`managed`](#managed) : politiques de paramètres gérés par groupe IdP37* [`managed`](#managed) : politiques de paramètres gérés par groupe IdP
38* [`telemetry`](#telemetry) : transfert OTLP vers votre pile d'observabilité38* [`telemetry`](#telemetry) : transfert OTLP vers votre pile d'observabilité
65| `port` | Non | Port de liaison. Par défaut `8080`. |65| `port` | Non | Port de liaison. Par défaut `8080`. |
66| `public_url` | Sauf si `host` est loopback | L'origine `https://` visible en externe, utilisée pour construire le `redirect_uri` IdP et les métadonnées de découverte. Requis chaque fois que `host` n'est pas une adresse loopback, que TLS se termine à un proxy tel qu'un ALB, Ingress ou Cloud Run ou à la passerelle elle-même via `tls`, car la passerelle ne dérive jamais sa propre origine à partir des en-têtes `X-Forwarded-*` ; ils sont spoofables par le client. L'amorçage échoue sans lui. `trusted_proxies` ci-dessous régit uniquement la résolution de l'IP du client. Également requis pour activer la [télémétrie](#telemetry), car la passerelle construit le point de terminaison OTLP qu'elle pousse aux clients à partir de cette URL. |66| `public_url` | Sauf si `host` est loopback | L'origine `https://` visible en externe, utilisée pour construire le `redirect_uri` IdP et les métadonnées de découverte. Requis chaque fois que `host` n'est pas une adresse loopback, que TLS se termine à un proxy tel qu'un ALB, Ingress ou Cloud Run ou à la passerelle elle-même via `tls`, car la passerelle ne dérive jamais sa propre origine à partir des en-têtes `X-Forwarded-*` ; ils sont spoofables par le client. L'amorçage échoue sans lui. `trusted_proxies` ci-dessous régit uniquement la résolution de l'IP du client. Également requis pour activer la [télémétrie](#telemetry), car la passerelle construit le point de terminaison OTLP qu'elle pousse aux clients à partir de cette URL. |
67| `tls.cert` / `tls.key` | Non | Chemins PEM si la passerelle termine TLS elle-même |67| `tls.cert` / `tls.key` | Non | Chemins PEM si la passerelle termine TLS elle-même |
68| `trusted_proxies` | Non | CIDRs ou IPs des équilibreurs de charge devant la passerelle. Lorsqu'il est défini, la passerelle fait confiance à `X-Forwarded-For` uniquement à partir de ces pairs et enregistre l'IP client réelle pour la limitation de débit par IP et l'audit. Équivalent à nginx `set_real_ip_from`. |68| `trusted_proxies` | Non | CIDRs ou IPs des équilibreurs de charge devant la passerelle. Lorsqu'il est défini, la passerelle fait confiance à `X-Forwarded-For` uniquement à partir de ces pairs et enregistre l'IP client réelle pour la limitation de débit par IP et l'audit. Équivalent à nginx `set_real_ip_from`. Les entrées `X-Forwarded-For` écrites en tant que `ipv4:port` ou `[ipv6]:port`, comme certains équilibreurs de charge le font, sont lues avec le port supprimé. Une adresse IPv6 avec un port ajouté et sans crochets peut être lue comme une adresse différente ou ne pas être lue du tout, donc désactivez l'option de port sur tout proxy qui écrit cette forme. |
69 69
70<h3 id="oidc">70<h3 id="oidc">
71 `oidc`71 `oidc`
76OpenID Connect (OIDC) est le protocole SSO que la passerelle utilise avec votre fournisseur d'identité ; voir [Configuration du fournisseur d'identité](/docs/fr/claude-apps-gateway-deploy#identity-provider-setup) pour ce qu'il faut enregistrer du côté IdP.76OpenID Connect (OIDC) est le protocole SSO que la passerelle utilise avec votre fournisseur d'identité ; voir [Configuration du fournisseur d'identité](/docs/fr/claude-apps-gateway-deploy#identity-provider-setup) pour ce qu'il faut enregistrer du côté IdP.
77 77
78| Champ | Requis | Description |78| Champ | Requis | Description |
79| ------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |79| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80| `issuer` | Oui | Base de découverte OIDC. Doit servir la découverte à `/.well-known/openid-configuration`. Utilisez HTTPS en production ; la passerelle accepte un émetteur `http://`. Un émetteur de boucle locale tel que `http://localhost:8081` est rejeté par la [garde SSRF](/docs/fr/claude-apps-gateway-deploy#threat-model-summary) sauf si `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` est défini dans l'environnement de la passerelle. |80| `issuer` | Oui | Base de découverte OIDC. Doit servir la découverte à `/.well-known/openid-configuration`. Utilisez HTTPS en production ; la passerelle accepte un émetteur `http://`. Un émetteur de boucle locale tel que `http://localhost:8081` est rejeté par la [garde SSRF](/docs/fr/claude-apps-gateway-deploy#threat-model-summary) sauf si `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` est défini dans l'environnement de la passerelle. |
81| `client_id` / `client_secret` | Oui | De votre enregistrement de client OAuth |81| `client_id` / `client_secret` | Oui | De votre enregistrement de client OAuth |
82| `allowed_email_domains` | Non | Rejeter les id\_tokens dont la réclamation `email` n'est pas dans l'un de ces domaines, insensible à la casse. Défense en profondeur contre les erreurs de configuration IdP multi-locataires. Indépendamment de ce paramètre, un id\_token dont la réclamation `email_verified` est explicitement `false` est toujours rejeté. |82| `allowed_email_domains` | Non | Rejeter les id\_tokens dont la réclamation `email` n'est pas dans l'un de ces domaines, insensible à la casse. Défense en profondeur contre les erreurs de configuration IdP multi-locataires. Indépendamment de ce paramètre, un id\_token dont la réclamation `email_verified` est explicitement `false` est toujours rejeté. |
85| `google_groups` | Non | Rechercher les groupes de l'utilisateur connecté via l'API Google Workspace Admin SDK Directory, car le id\_token de Google ne porte aucune réclamation de groupes. Définissez `service_account_json_path` sur un fichier de clé de compte de service avec délégation à l'échelle du domaine sur la portée `https://www.googleapis.com/auth/admin.directory.group.readonly`, et `admin_email` sur un administrateur Workspace que le compte de service usurpe ; l'API Directory nécessite un sujet administrateur réel. Les adresses e-mail de groupe de chaque utilisateur deviennent leur réclamation de groupes, donc `allowed_groups` et `managed.policies.match.groups` correspondent sur les e-mails de groupe. |85| `google_groups` | Non | Rechercher les groupes de l'utilisateur connecté via l'API Google Workspace Admin SDK Directory, car le id\_token de Google ne porte aucune réclamation de groupes. Définissez `service_account_json_path` sur un fichier de clé de compte de service avec délégation à l'échelle du domaine sur la portée `https://www.googleapis.com/auth/admin.directory.group.readonly`, et `admin_email` sur un administrateur Workspace que le compte de service usurpe ; l'API Directory nécessite un sujet administrateur réel. Les adresses e-mail de groupe de chaque utilisateur deviennent leur réclamation de groupes, donc `allowed_groups` et `managed.policies.match.groups` correspondent sur les e-mails de groupe. |
86| `email_claim` | Non | Quelle réclamation id\_token porte l'e-mail de l'utilisateur. Par défaut `email`. Certains IdPs, tels que ADFS et Entra B2C, émettent `upn` ou `preferred_username` à la place. Accepte une clé plate, un pointeur JSON ou une liste de clés de secours où la première clé présente est utilisée. |86| `email_claim` | Non | Quelle réclamation id\_token porte l'e-mail de l'utilisateur. Par défaut `email`. Certains IdPs, tels que ADFS et Entra B2C, émettent `upn` ou `preferred_username` à la place. Accepte une clé plate, un pointeur JSON ou une liste de clés de secours où la première clé présente est utilisée. |
87| `scopes` | Non | Remplacement complet des portées OIDC que la passerelle demande. Par défaut `[openid, profile, email, offline_access]`. Définissez lorsque votre IdP rejette les portées qu'il ne reconnaît pas, ou nécessite une portée personnalisée pour émettre des groupes ou un e-mail. Doit inclure `openid`. Supprimer `offline_access` désactive les jetons d'actualisation, donc les développeurs réexécutent la connexion au navigateur tous les `session.ttl_hours`. Voir [Configuration du fournisseur d'identité](/docs/fr/claude-apps-gateway-deploy#identity-provider-setup) pour les recettes de portée par IdP telles que le flux de jeton d'actualisation de Google. |87| `scopes` | Non | Remplacement complet des portées OIDC que la passerelle demande. Par défaut `[openid, profile, email, offline_access]`. Définissez lorsque votre IdP rejette les portées qu'il ne reconnaît pas, ou nécessite une portée personnalisée pour émettre des groupes ou un e-mail. Doit inclure `openid`. Supprimer `offline_access` désactive les jetons d'actualisation, donc les développeurs réexécutent la connexion au navigateur tous les `session.ttl_hours`. Voir [Configuration du fournisseur d'identité](/docs/fr/claude-apps-gateway-deploy#identity-provider-setup) pour les recettes de portée par IdP telles que le flux de jeton d'actualisation de Google. |
88| `scope_on_refresh` | Non | Envoyer également `scope`, avec la même liste que la demande de connexion, lorsque la passerelle échange un jeton d'actualisation. Par défaut `false` : la demande d'actualisation omet `scope`. La plupart des IdPs retournent un id\_token à chaque actualisation et n'en ont pas besoin. Définissez `true` lorsque votre IdP retourne un id\_token lors de l'actualisation uniquement s'il est demandé à nouveau pour `openid`, ce qu'Okta documente pour sa subvention d'actualisation. Sans id\_token, chaque actualisation dépend du point de terminaison userinfo de l'IdP acceptant le jeton d'accès actualisé. Si vous contrôlez la connexion ou les politiques de correspondance sur les groupes et que le id\_token de votre IdP au moment de l'actualisation les omet, définissez également `userinfo_fallback: true` pour que la passerelle les remplisse à partir du point de terminaison userinfo. Un IdP qui a accordé moins de portées que demandé peut rejeter l'actualisation avec `invalid_scope`, y compris pour les sessions existantes si vous ajoutez des entrées à `scopes` pendant que ceci est activé. Décochez la clé si les actualisations commencent à échouer à `token_endpoint` après l'avoir définie. Nécessite Claude Code v2.1.260 ou ultérieur sur le serveur de la passerelle. |
88| `extra_auth_params` | Non | Paramètres de requête supplémentaires ajoutés à la demande d'autorisation IdP, textuellement. C'est le mécanisme de remplacement pour le comportement spécifique à l'IdP, tel que `access_type: offline` pour les jetons d'actualisation Google, `domain_hint` pour certains locataires Entra, ou `acr_values` pour les flux d'escalade. Ne peut pas remplacer les paramètres de protocole gérés par la passerelle : `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode` et `client_id`. |89| `extra_auth_params` | Non | Paramètres de requête supplémentaires ajoutés à la demande d'autorisation IdP, textuellement. C'est le mécanisme de remplacement pour le comportement spécifique à l'IdP, tel que `access_type: offline` pour les jetons d'actualisation Google, `domain_hint` pour certains locataires Entra, ou `acr_values` pour les flux d'escalade. Ne peut pas remplacer les paramètres de protocole gérés par la passerelle : `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode` et `client_id`. |
89| `userinfo_fallback` | Non | Lorsque le id\_token omet l'e-mail ou les groupes, les récupérer à partir de `/userinfo`. Nécessaire pour les jetons d'accès légers Keycloak, le serveur org Okta et les jetons minimaux ADFS. Le id\_token reste faisant autorité ; userinfo remplit uniquement les lacunes. Par défaut `false`. |90| `userinfo_fallback` | Non | Lorsque le id\_token omet l'e-mail ou les groupes, les récupérer à partir de `/userinfo`. Nécessaire pour les jetons d'accès légers Keycloak, le serveur org Okta et les jetons minimaux ADFS. Le id\_token reste faisant autorité ; userinfo remplit uniquement les lacunes. Par défaut `false`. |
90| `use_pkce` | Non | Envoyer un défi PKCE (S256) sur la demande d'autorisation. Par défaut `true`. Définissez `false` uniquement si votre IdP rejette PKCE pour ce client confidentiel. |91| `use_pkce` | Non | Envoyer un défi PKCE (S256) sur la demande d'autorisation. Par défaut `true`. Définissez `false` uniquement si votre IdP rejette PKCE pour ce client confidentiel. |
135 `upstreams`136 `upstreams`
136</h3>137</h3>
137 138
138`upstreams` est une liste ordonnée. La passerelle transfère l'inférence au premier upstream qui résout le modèle demandé. Sur `5xx`, `429`, `401`, `403`, `404`, ou timeout, elle bascule vers le suivant ; les autres `4xx` ne le font pas, car ces erreurs sont attribuables à la demande plutôt qu'à l'upstream. Un `401` ou `403` signifie que l'identifiant propre de la passerelle a échoué contre cet upstream, et un `404` signifie que cet upstream ne sert pas le modèle demandé, donc un upstream ultérieur dans la liste peut toujours le faire.139`upstreams` est une liste ordonnée. La passerelle transfère l'inférence au premier upstream qui résout le modèle demandé.
140
141Sur `5xx`, `429`, `401`, `403`, `404`, ou timeout, la passerelle bascule vers le suivant ; les autres `4xx` ne le font pas, car ces erreurs sont attribuables à la demande plutôt qu'à l'upstream. Un `401` ou `403` signifie que l'identifiant propre de la passerelle a échoué contre cet upstream. Un `404` signifie que cet upstream ne sert pas le modèle demandé, donc un upstream ultérieur dans la liste peut toujours le faire.
142
143Si vous définissez `forward_user_identity: true` sur un upstream, un `429` qu'il retourne à une demande qui portait l'e-mail du développeur ne bascule pas. Voir [comment un déni de limite par utilisateur atteint le développeur](#per-user-identity-headers-for-a-proxy-you-run).
139 144
140Le basculement sur `404` nécessite la passerelle v2.1.198 ou ultérieure. Les versions antérieures retournaient le premier `404` au client même lorsqu'un upstream ultérieur dans la liste servait le modèle.145Le basculement sur `404` nécessite la passerelle v2.1.198 ou ultérieure. Les versions antérieures retournaient le premier `404` au client même lorsqu'un upstream ultérieur dans la liste servait le modèle.
141 146
227 232
228Lorsque le jeton IdP ne porte pas d'e-mail, la passerelle envoie uniquement `x-claude-gateway-user-id` et omet les deux en-têtes d'e-mail. Si votre IdP met l'e-mail dans une réclamation différente, définissez [`oidc.email_claim`](#oidc) sur cette réclamation.233Lorsque le jeton IdP ne porte pas d'e-mail, la passerelle envoie uniquement `x-claude-gateway-user-id` et omet les deux en-têtes d'e-mail. Si votre IdP met l'e-mail dans une réclamation différente, définissez [`oidc.email_claim`](#oidc) sur cette réclamation.
229 234
235Lorsque votre proxy répond `429` à une demande qui portait l'e-mail du développeur, la passerelle retourne cette réponse au développeur telle quelle au lieu de basculer vers le prochain upstream, donc votre limite de budget ou de débit par utilisateur du proxy tient. Les autres réponses du proxy suivent les [règles de basculement](#upstreams) ordinaires. Si le jeton IdP d'un développeur ne porte pas d'e-mail, la passerelle transfère ses demandes sans les en-têtes d'e-mail, donc un `429` à l'une de ces demandes compte comme capacité d'upstream et bascule. Avant v2.1.267 sur le serveur de la passerelle, chaque `429` basculait.
236
230Définissez `forward_user_identity` uniquement sur un upstream dont le `base_url` est un proxy que vous exploitez. La passerelle envoie les e-mails des développeurs à quel que soit le serveur que ce `base_url` nomme. Si le `base_url` est l'API Anthropic, qui est la valeur par défaut, la passerelle refuse de démarrer.237Définissez `forward_user_identity` uniquement sur un upstream dont le `base_url` est un proxy que vous exploitez. La passerelle envoie les e-mails des développeurs à quel que soit le serveur que ce `base_url` nomme. Si le `base_url` est l'API Anthropic, qui est la valeur par défaut, la passerelle refuse de démarrer.
231 238
232<h4 id="amazon-bedrock">239<h4 id="amazon-bedrock">
257Les identifiants explicites doivent être complets : la passerelle échoue au démarrage lorsque `aws_access_key_id` et `aws_secret_access_key` ne sont pas définis ensemble, ou lorsque `aws_session_token` est défini sans eux. Avant v2.1.207, un bloc `auth:` partiel passait la validation.264Les identifiants explicites doivent être complets : la passerelle échoue au démarrage lorsque `aws_access_key_id` et `aws_secret_access_key` ne sont pas définis ensemble, ou lorsque `aws_session_token` est défini sans eux. Avant v2.1.207, un bloc `auth:` partiel passait la validation.
258 265
259| Configuration | Comment |266| Configuration | Comment |
260| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |267| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
261| Permissions IAM | Accordez au principal de la passerelle `bedrock:InvokeModel` et `bedrock:InvokeModelWithResponseStream` sur les ARNs de profil d'inférence et les ARNs de modèle de fondation sous-jacents. Pour le catalogue intégré dans les régions US : `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` et `arn:aws:bedrock:*::foundation-model/anthropic.*`. |268| Permissions IAM | Accordez au principal de la passerelle `bedrock:InvokeModel` et `bedrock:InvokeModelWithResponseStream` sur les ARNs de profil d'inférence et les ARNs de modèle de fondation sous-jacents. Pour le catalogue intégré dans les régions US : `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` et `arn:aws:bedrock:*::foundation-model/anthropic.*`. Accordez également `bedrock:CountTokens` sur les ARNs de modèle de fondation. La passerelle l'utilise, sans frais, pour compter les jetons d'entrée d'une demande que le client a abandonnée, donc les [limites de dépenses](#admin) restent exactes. Sans cela, la passerelle revient à une demande Bedrock d'un jeton pour ce compte. |
262| Accès au modèle | Amazon Bedrock active l'accès au modèle par défaut dans les régions commerciales. La porte au niveau du compte restante est celle d'Anthropic : un formulaire d'utilisation unique. Si personne dans votre compte AWS ne l'a soumis, ouvrez la console Amazon Bedrock, sélectionnez un modèle Anthropic dans le catalogue de modèles et complétez le formulaire. Voir [Soumettre les détails du cas d'utilisation](/docs/fr/amazon-bedrock#1-submit-use-case-details) pour le formulaire AWS Organizations et les permissions dont le soumetteur a besoin. |269| Accès au modèle | Amazon Bedrock active l'accès au modèle par défaut dans les régions commerciales. La porte au niveau du compte restante est celle d'Anthropic : un formulaire d'utilisation unique. Si personne dans votre compte AWS ne l'a soumis, ouvrez la console Amazon Bedrock, sélectionnez un modèle Anthropic dans le catalogue de modèles et complétez le formulaire. Voir [Soumettre les détails du cas d'utilisation](/docs/fr/amazon-bedrock#1-submit-use-case-details) pour le formulaire AWS Organizations et les permissions dont le soumetteur a besoin. |
263| EKS (IRSA) | Créez un rôle IAM avec la politique ci-dessus et une politique de confiance pour le fournisseur OIDC de votre cluster limité au compte de service de la passerelle. Annotez le compte de service avec `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`. `auth: {}` le récupère. |270| EKS (IRSA) | Créez un rôle IAM avec la politique ci-dessus et une politique de confiance pour le fournisseur OIDC de votre cluster limité au compte de service de la passerelle. Annotez le compte de service avec `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`. `auth: {}` le récupère. |
264| ECS / EC2 | Attachez le rôle IAM à la définition de tâche ou au profil d'instance. `auth: {}` le récupère. |271| ECS / EC2 | Attachez le rôle IAM à la définition de tâche ou au profil d'instance. `auth: {}` le récupère. |
366 373
367La passerelle essaie les upstreams dans l'ordre. `5xx`, `429`, `401`, `403`, `404`, timeouts et point de terminaison manquant (`501`) basculent ; les autres `4xx` ne le font pas.374La passerelle essaie les upstreams dans l'ordre. `5xx`, `429`, `401`, `403`, `404`, timeouts et point de terminaison manquant (`501`) basculent ; les autres `4xx` ne le font pas.
368 375
369`429` est la capacité par upstream, donc l'épuisement du débit provisionné (PT) bascule vers la demande. `404` est la disponibilité du modèle par upstream, donc un upstream qui n'a pas activé un modèle ne bloque pas un upstream ultérieur qui le sert. Un upstream qui ne peut pas résoudre le modèle demandé est ignoré sans un aller-retour réseau.376`429` est la capacité par upstream, donc l'épuisement du débit provisionné (PT) bascule vers la demande. Si vous définissez [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) sur un upstream, un `429` à une demande qui portait l'e-mail du développeur est un déni par utilisateur au lieu et ne bascule pas.
377
378`404` est la disponibilité du modèle par upstream, donc un upstream qui n'a pas activé un modèle ne bloque pas un upstream ultérieur qui le sert. Un upstream qui ne peut pas résoudre le modèle demandé est ignoré sans un aller-retour réseau.
370 379
371Cet exemple route une allocation Bedrock de débit provisionné en premier, déborde vers la demande et un deuxième compte, et revient à l'API Anthropic en dernier :380Cet exemple route une allocation Bedrock de débit provisionné en premier, déborde vers la demande et un deuxième compte, et revient à l'API Anthropic en dernier :
372 381
426 `admin`435 `admin`
427</h3>436</h3>
428 437
429Optionnel. Active `/v1/organizations/spend_limits`, qui reflète l'API Admin publique d'Anthropic, et l'application de dépenses par développeur sur `/v1/messages`. Voir [Limites de dépenses](/docs/fr/claude-apps-gateway-spend-limits) pour comment les plafonds sont définis et appliqués ; cette section couvre les clés `gateway.yaml` qui activent la fonctionnalité et l'ajustent.438Optionnel. Active `/v1/organizations/spend_limits`, qui reflète l'API Admin publique d'Anthropic, et l'application des dépenses par développeur sur `/v1/messages`. Consultez [Limites de dépenses](/docs/fr/claude-apps-gateway-spend-limits) pour savoir comment les plafonds sont définis et appliqués ; cette section couvre les clés `gateway.yaml` qui activent la fonctionnalité et l'ajustent.
430 439
431```yaml theme={null}440```yaml theme={null}
432admin:441admin:
433 # Clés API statiques nommées pour les points de terminaison admin, envoyées en tant que x-api-key.442 # Clés API statiques nommées pour les points de terminaison admin, envoyées en tant que x-api-key.
434 # L'id apparaît dans le journal d'audit en tant que admin-key:<id> donc chaque clé est443 # L'id apparaît dans le journal d'audit en tant que admin-key:<id> afin que chaque clé soit
435 # attribuable. Tableau pour la rotation : ajoutez la nouvelle clé, déployez les clients,444 # attribuable. Tableau pour la rotation : ajoutez la nouvelle clé, déployez les clients,
436 # supprimez l'ancienne.445 # supprimez l'ancienne.
437 write_keys:446 write_keys:
439 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }448 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
440 read_keys:449 read_keys:
441 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }450 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
442 # Groupes IdP accordés un accès administrateur complet via le JWT de passerelle normal (pas de clé API).451 # Groupes IdP disposant d'un accès admin complet via le JWT de passerelle normal (pas de clé API).
443 admin_groups: [platform-finops]452 admin_groups: [platform-finops]
444 blocked_message: demander une augmentation à https://go.example.com/claude-limits453 blocked_message: request an increase at https://go.example.com/claude-limits
445```454```
446 455
447| Champ | Requis | Description |456| Champ | Requis | Description |
448| ------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |457| ------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
449| `write_keys` | Non | Tableau de `{id, key}`. Un `x-api-key` correspondant à l'un de ceux-ci peut lister, définir et supprimer les limites de dépenses. Les valeurs de clé doivent être au moins 32 caractères ; les `id`s doivent être uniques dans `read_keys` et `write_keys`. |458| `write_keys` | Non | Tableau de `{id, key}`. Une `x-api-key` correspondant à l'une de ces clés peut lister, définir et supprimer les limites de dépenses. Les valeurs de clé doivent comporter au moins 32 caractères ; les `id` doivent être uniques dans `read_keys` et `write_keys`. |
450| `read_keys` | Non | Tableau de `{id, key}`. Lecture seule : chaque point de terminaison `GET`, y compris la liste des plafonds, la récupération d'un par ID et la lecture de [`/effective`](/docs/fr/claude-apps-gateway-spend-limits#%2Feffective) et [`/audit`](/docs/fr/claude-apps-gateway-spend-limits#%2Faudit). |459| `read_keys` | Non | Tableau de `{id, key}`. Lecture seule : tous les points de terminaison `GET`, y compris le listage des plafonds, la récupération d'un par ID, et la lecture de [`/effective`](/docs/fr/claude-apps-gateway-spend-limits#%2Feffective) et [`/audit`](/docs/fr/claude-apps-gateway-spend-limits#%2Faudit). |
451| `admin_groups` | Non | Noms de groupes IdP. Un JWT de passerelle dont la réclamation `groups` inclut l'un de ceux-ci a un accès administrateur complet, lecture et écriture, et audite en tant que `oidc:<sub>`. Utilisez ceci pour les administrateurs humains ; utilisez les clés API pour les machines. Une entrée vide dans cette liste arrête la passerelle au démarrage. Voir [Valeurs de correspondance qui arrêtent la passerelle au démarrage](#matcher-values-that-stop-the-gateway-at-boot). |460| `admin_groups` | Non | Noms de groupes IdP. Un JWT de passerelle dont la revendication `groups` inclut l'un de ces groupes dispose d'un accès admin complet, lecture et écriture, et effectue un audit en tant que `oidc:<sub>`. Utilisez ceci pour les administrateurs humains ; utilisez les clés API pour les machines. Une entrée vide dans cette liste arrête la passerelle au démarrage. Consultez [Valeurs de correspondance qui arrêtent la passerelle au démarrage](#matcher-values-that-stop-the-gateway-at-boot). |
452| `blocked_message` | Non | Ajouté textuellement au `429 billing_error` qu'un développeur bloqué voit. Écrivez l'instruction complète, telle qu'une URL ou un canal Slack. Non défini, la passerelle envoie uniquement le message par défaut. Voir [Comment l'application fonctionne](/docs/fr/claude-apps-gateway-spend-limits#how-enforcement-works). |461| `blocked_message` | Non | Ajouté textuellement à l'erreur `429 billing_error` qu'un développeur bloqué voit. Écrivez l'instruction complète, comme une URL ou un canal Slack. Lorsqu'il n'est pas défini, la passerelle envoie uniquement le message par défaut. Consultez [Comment l'application fonctionne](/docs/fr/claude-apps-gateway-spend-limits#how-enforcement-works). |
453| `audit_retention_days` | Non | Par défaut `365`. Les lignes `admin_audit` plus anciennes sont balayées. |462| `audit_retention_days` | Non | Par défaut `365`. Les lignes `admin_audit` plus anciennes sont supprimées. |
454| `spend_retention_months` | Non | Par défaut `13`. Les lignes du compteur `spend` plus anciennes que ceci sont balayées. La valeur par défaut conserve une année complète plus le mois partiel actuel pour les rapports d'année en année. |463| `spend_retention_months` | Non | Par défaut `13`. Les lignes du compteur `spend` plus anciennes que cela sont supprimées. La valeur par défaut conserve une année complète plus le mois partiel actuel pour les rapports d'une année sur l'autre. |
455| `identity_retention_days` | Non | Par défaut `90`. TTL de dernière vue pour les lignes `principal_emails`, qui contiennent l'e-mail, le nom d'affichage et les groupes de chaque développeur (PII). Délibérément plus court que la rétention des dépenses pour qu'une identité déprovisionée vieillit tandis que ses compteurs de dépenses anonymes restent. |464| `identity_retention_days` | Non | Par défaut `90`. TTL de dernière consultation pour les lignes `principal_emails`, qui contiennent l'e-mail, le nom d'affichage et les groupes de chaque développeur (données personnelles). Délibérément plus court que la rétention des dépenses afin qu'une identité déprovisionée expire tandis que ses compteurs de dépenses anonymes restent. |
456| `group_limit_mode` | Non | `min` (par défaut) ou `max`. Lorsqu'un développeur est dans plusieurs groupes avec des plafonds, `min` applique le plus restrictif et `max` le moins. Utilisé à la fois par l'application et `/effective`. |465| `group_limit_mode` | Non | `min` (par défaut) ou `max`. Lorsqu'un développeur se trouve dans plusieurs groupes avec des plafonds, `min` applique le plus restrictif et `max` le moins restrictif. Utilisé à la fois par l'application et par `/effective`. |
457 466
458<h3 id="enforcement">467<h3 id="enforcement">
459 `enforcement`468 `enforcement`
460</h3>469</h3>
461 470
462Le bloc `enforcement` contrôle comment les vérifications de limite de dépenses se comportent lorsque le magasin n'est pas disponible.471Le bloc `enforcement` contrôle le comportement des vérifications de limite de dépenses lorsque le magasin est indisponible.
463 472
464| Champ | Requis | Description |473| Champ | Requis | Description |
465| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |474| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
466| `fail_closed_on_error` | Non | Par défaut `false`. L'application de dépenses échoue ouvertement sur une panne Postgres, donc l'inférence reste active. Définissez `true` pour échouer fermé : les développeurs au-dessus du plafond sont bloqués, mais tout le monde l'est aussi si le magasin est inaccessible. Nécessite un bloc [`admin:`](#admin) : l'application de dépenses s'exécute uniquement lorsque `admin` est configuré, et la passerelle refuse de démarrer si vous définissez ceci `true` sans un. |475| `fail_closed_on_error` | Non | Par défaut `false`. L'application des limites de dépenses échoue ouvertement en cas de panne Postgres, afin que l'inférence reste active. Définissez `true` pour échouer fermé : les développeurs au-delà du plafond sont bloqués, mais tout le monde l'est aussi si le magasin est inaccessible. Nécessite un bloc [`admin:`](#admin) : l'application des limites de dépenses ne s'exécute que lorsque `admin` est configuré, et la passerelle refuse de démarrer si vous définissez ceci à `true` sans un. |
467 476
468<h3 id="pricing">477<h3 id="pricing">
469 `pricing`478 `pricing`
470</h3>479</h3>
471 480
472Le bloc `pricing` indique au compteur de dépenses quoi facturer au lieu du prix catalogue USD, donc les plafonds et [`/effective`](/docs/fr/claude-apps-gateway-spend-limits#%2Feffective) reflètent vos tarifs contractés. Les montants restent en USD et restent une estimation, pas une facture. Deux conditions préalables :481Le bloc `pricing` indique au compteur de dépenses ce qu'il faut facturer au lieu du prix catalogue USD, afin que les plafonds et [`/effective`](/docs/fr/claude-apps-gateway-spend-limits#%2Feffective) reflètent vos tarifs contractuels. Les montants restent en USD et restent une estimation, pas une facture. Deux conditions préalables :
473 482
474* Claude Code v2.1.227 ou ultérieur sur le serveur de passerelle. Les versions antérieures rejettent la clé inconnue au démarrage.483* Claude Code v2.1.227 ou ultérieur sur le serveur de passerelle. Les versions antérieures rejettent la clé inconnue au démarrage.
475* Un bloc [`admin:`](#admin), car seul le compteur de dépenses lit `pricing`. La passerelle refuse de démarrer avec `pricing` défini et aucun `admin`.484* Un bloc [`admin:`](#admin) ou, dans v2.1.268 ou ultérieur, un bloc [`managed:`](#managed) avec au moins une politique. La passerelle refuse de démarrer avec `pricing` défini et aucun bloc, car rien ne le lirait.
476 485
477```yaml theme={null}486```yaml theme={null}
478pricing:487pricing:
487```496```
488 497
489| Champ | Requis | Description |498| Champ | Requis | Description |
490| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |499| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
491| `multiplier` | Non | Par défaut `1`. Le compteur multiplie chaque montant mesuré par ceci, qu'il soit au prix catalogue ou remplacé, donc `0.85` facture 85 % du prix. Doit être supérieur à 0 et au maximum 1. |500| `multiplier` | Non | Par défaut `1`. Le compteur multiplie chaque montant mesuré par ceci, qu'il soit au prix catalogue ou remplacé, donc `0.85` facture 85 % du prix. Doit être supérieur à 0 et au maximum 1. |
492| `overrides` | Non | Lignes de `{upstream, model, input, output, cache_read, cache_write}` en USD par million de jetons. Les quatre tarifs sont requis et doivent être positifs. |501| `overrides` | Non | Lignes de `{upstream, model, input, output, cache_read, cache_write}` en USD par million de jetons. Les quatre tarifs sont obligatoires. Chacun doit être supérieur à 0 et au maximum 10 000. |
493 502
494Comment le compteur correspond à une ligne de remplacement :503Comment le compteur correspond à une ligne de remplacement :
495 504
496* Une ligne remplace le prix catalogue pour les demandes que `upstream`, un [`upstreams[].name`](#upstreams), sert pour `model`. Cela inclut le tarif [mode rapide](/docs/fr/fast-mode#understand-the-cost-tradeoff) plus élevé, donc les demandes en mode rapide et standard sont mesurées aux mêmes quatre tarifs.505* Une ligne remplace le prix catalogue pour les demandes que `upstream`, un [`upstreams[].name`](#upstreams), traite pour `model`. Cela inclut le tarif [mode rapide](/docs/fr/fast-mode#understand-the-cost-tradeoff) plus élevé, donc les demandes en mode rapide et standard sont mesurées aux mêmes quatre tarifs.
497* Un ID intégré tel que `claude-sonnet-4-6`, correspondant comme [`models[].id`](#models), couvre chaque forme datée, forme régionale Amazon Bedrock, ou forme Google Cloud Agent Platform que le compteur évalue comme ce modèle. Toute autre chaîne, telle qu'un alias ou un ARN de profil d'inférence, correspond à l'ID que le client a envoyé ou à la chaîne envoyée en amont, insensible à la casse.506* Un ID intégré tel que `claude-sonnet-4-6`, correspondant comme [`models[].id`](#models), couvre chaque forme datée, forme Amazon Bedrock régionale, ou forme Google Cloud Agent Platform que le compteur évalue comme ce modèle. Toute autre chaîne, comme un alias ou un ARN de profil d'inférence, correspond à l'ID que le client a envoyé ou à la chaîne envoyée en amont, insensible à la casse.
498* Lorsque les lignes se chevauchent, le compteur choisit la ligne la plus spécifique plutôt que la première ligne : une ligne dont `model` est la chaîne de modèle exacte envoyée en amont, puis une ligne correspondant à l'ID exact que le client a envoyé, puis une ligne nommant le modèle intégré.507* Lorsque les lignes se chevauchent, le compteur choisit la ligne la plus spécifique plutôt que la première ligne : une ligne dont `model` est la chaîne de modèle exacte envoyée en amont, puis une ligne correspondant à l'ID exact que le client a envoyé, puis une ligne nommant le modèle intégré.
499* Un nom upstream inconnu échoue au démarrage, tout comme deux lignes pour un upstream qui nomment le même modèle, y compris deux orthographes d'un modèle intégré. La passerelle avertit au démarrage à propos d'une ligne qu'aucun modèle demandable ne peut utiliser.508* Un nom d'upstream inconnu échoue au démarrage, tout comme deux lignes pour un upstream qui nomment le même modèle, y compris deux orthographes d'un modèle intégré. La passerelle avertit au démarrage à propos d'une ligne qu'aucun modèle demandable ne peut utiliser.
500* Les demandes de recherche Web restent au prix catalogue \$0.01 ; le multiplicateur s'applique toujours à elles.509* Les demandes de recherche Web restent au prix catalogue de \$0,01 ; le multiplicateur s'y applique toujours.
501 510
502Pour les tarifs par région, donnez à chaque région son propre upstream nommé et une ligne par upstream.511Pour les tarifs par région, donnez à chaque région son propre upstream nommé et une ligne par upstream.
503 512
513<h4 id="send-the-rates-to-signed-in-clients">
514 Envoyer les tarifs aux clients connectés
515</h4>
516
517Avec v2.1.268 ou ultérieur sur le serveur de passerelle, la passerelle place également les tarifs de `pricing` dans les politiques [`managed`](#managed) qu'elle sert, en tant que paramètre géré [`modelPricing`](/docs/fr/settings-reference#modelpricing). Les développeurs correspondant à une politique voient alors les tarifs `pricing` pour le premier upstream qui sert chaque ID de modèle dans `/usage`, la ligne d'état et OpenTelemetry. Un développeur qui ne correspond à aucune politique ne reçoit aucun paramètre géré, donc ses chiffres restent au prix catalogue. Les clients appliquent le paramètre dans Claude Code v2.1.242 ou ultérieur.
518
519* Ce que la passerelle ajoute : à moins qu'un bloc `cli` de politique ne définisse déjà `modelPricing`, la passerelle ajoute le `multiplier` et, pour chaque ID de modèle qu'un client peut demander, la ligne de remplacement du premier upstream qui sert cet ID. Un tarif que seul un upstream de basculement facture reste sur la passerelle.
520* Exclure une politique : définissez `modelPricing` à `{}` dans le bloc `cli` de cette politique, et ses développeurs restent au prix catalogue.
521* Conserver les tarifs propres d'une politique : une politique dont le bloc `cli` définit `modelPricing` avec son propre `multiplier` ou `overrides` conserve ce `modelPricing` entièrement, et la passerelle n'ajoute aucun tarif qui lui est propre.
522
504<h3 id="models">523<h3 id="models">
505 `models`524 `models`
506</h3>525</h3>
507 526
508Le bloc `models` est une liste de modèles curée par l'administrateur optionnelle, servie à `/v1/models` et utilisée pour traduire les IDs de modèle par upstream. Elle est requise pour les régions Bedrock non-US, les ARNs de débit provisionné Bedrock et les noms de déploiement Foundry.527Le bloc `models` est une liste de modèles optionnelle organisée par l'administrateur, servie à `/v1/models` et utilisée pour traduire les ID de modèles par upstream. Elle est obligatoire pour les régions Amazon Bedrock non-US, les ARN de débit provisionné Amazon Bedrock et les noms de déploiement Microsoft Foundry.
509 528
510```yaml theme={null}529```yaml theme={null}
511auto_include_builtin_models: true # false : exposer uniquement la liste ci-dessous530auto_include_builtin_models: true # false: expose only the list below
512models:531models:
513 - id: claude-opus-4-8532 - id: claude-opus-4-8
514 label: Claude Opus 4.8533 label: Claude Opus 4.8
515 # description: texte optionnel affiché dans les clients qui le surfacent534 # description: optional text shown in clients that surface it
516 upstream_model:535 upstream_model:
517 anthropic: claude-opus-4-8536 anthropic: claude-opus-4-8
518 bedrock: us.anthropic.claude-opus-4-8 # ou un ARN de profil d'inférence537 bedrock: us.anthropic.claude-opus-4-8 # or an inference-profile ARN
519 foundry: your-opus-deployment-name538 foundry: your-opus-deployment-name
520```539```
521 540
525 `managed`544 `managed`
526</h3>545</h3>
527 546
528Le bloc `managed` définit les politiques d'accès basées sur les rôles indexées sur les groupes IdP ou le domaine d'e-mail. Les politiques sont évaluées dans l'ordre ; la première correspondance est sélectionnée, puis fusionnée sur la base de capture-tout `match: {}` décrite ci-dessous. Elles sont servies par utilisateur à `GET /managed/settings` avec mise en cache ETag/304.547Le bloc `managed` définit les politiques d'accès basées sur les rôles basées sur les groupes IdP ou le domaine de messagerie. Les politiques sont évaluées dans l'ordre ; la première correspondance est sélectionnée, puis fusionnée sur la base de capture-tout `match: {}` décrite ci-dessous. Elles sont servies par utilisateur à `GET /managed/settings` avec mise en cache ETag/304.
529 548
530```yaml theme={null}549```yaml theme={null}
531managed:550managed:
532 policies:551 policies:
533 # Groupes spécifiques en premier.552 # Specific groups first.
534 - match: { groups: [eng-contractors] }553 - match: { groups: [eng-contractors] }
535 cli:554 cli:
536 availableModels: [claude-sonnet-4-6]555 availableModels: [claude-sonnet-4-6]
537 permissions: { deny: ["WebFetch", "WebSearch"] }556 permissions: { deny: ["WebFetch", "WebSearch"] }
538 # Capture-tout par défaut en dernier : correspond à tous les utilisateurs authentifiés.557 # Default catch-all last: matches everyone who authenticated.
539 - match: {}558 - match: {}
540 cli:559 cli:
541 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]560 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
543 562
544Une capture-tout `match: {}`, conventionnellement listée en dernier, est traitée comme une couche de base. Chaque autre politique hérite de toute clé qu'elle ne définit pas de la capture-tout, donc les entrées par rôle n'ont besoin que de lister ce qui diffère de la valeur par défaut de l'organisation. Les règles de fusion dépendent du type de clé :563Une capture-tout `match: {}`, conventionnellement listée en dernier, est traitée comme une couche de base. Chaque autre politique hérite de toute clé qu'elle ne définit pas de la capture-tout, donc les entrées par rôle n'ont besoin que de lister ce qui diffère de la valeur par défaut de l'organisation. Les règles de fusion dépendent du type de clé :
545 564
546* **Listes d'autorisation** : `availableModels` et `permissions.allow`. La liste d'une politique spécifique remplace complètement celle de la base.565* **Listes d'autorisation** : `availableModels` et `permissions.allow`. La liste d'une politique spécifique remplace entièrement celle de la base.
547* **Listes de refus et tableaux de hooks** : `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` et chaque tableau de type d'événement `hooks`. Ceux-ci prennent l'union de la base et de la politique, donc un refus à l'échelle de l'organisation ou un hook d'audit ne peut pas être accidentellement supprimé par un remplacement par rôle.566* **Listes de refus et tableaux de hooks** : `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` et chaque tableau d'événement de type `hooks`. Ceux-ci prennent l'union de la base et de la politique, afin qu'un refus à l'échelle de l'organisation ou un hook d'audit ne puisse pas être accidentellement supprimé par un remplacement par rôle.
548* **Clés de type enregistrement** : `env`, `modelOverrides` et `skillOverrides`. Ceux-ci fusionnent superficiellement, donc un bloc `env` par rôle remplace les clés qu'il définit et hérite du reste de la base.567* **Clés de type enregistrement** : `env`, `modelOverrides` et `skillOverrides`. Ceux-ci fusionnent superficiellement, donc un bloc `env` par rôle remplace les clés qu'il définit et hérite du reste de la base.
549 568
550`availableModels` est également appliqué côté serveur à `/v1/messages`, donc un modèle refusé retourne `400` indépendamment de ce que le client envoie.569`availableModels` est également appliqué côté serveur à `/v1/messages`, donc un modèle refusé retourne `400` indépendamment de ce que le client envoie.
554* Lorsque la valeur est manquante ou vide, la passerelle rejette la demande avec le message `model is required`. Cette vérification nécessite une passerelle exécutant Claude Code v2.1.228 ou ultérieur.573* Lorsque la valeur est manquante ou vide, la passerelle rejette la demande avec le message `model is required`. Cette vérification nécessite une passerelle exécutant Claude Code v2.1.228 ou ultérieur.
555* Lorsque la valeur est présente mais n'est pas une chaîne, la passerelle rejette la demande avec le message `model must be a string`. Nécessite une passerelle exécutant Claude Code v2.1.221 ou ultérieur.574* Lorsque la valeur est présente mais n'est pas une chaîne, la passerelle rejette la demande avec le message `model must be a string`. Nécessite une passerelle exécutant Claude Code v2.1.221 ou ultérieur.
556 575
557| Correspondant | Comportement |576| Correspondance | Comportement |
558| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |577| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
559| `match: {}` | Correspond à tous les utilisateurs authentifiés. Commencez par un de ceux-ci et ajoutez des politiques limitées au groupe plus tard. |578| `match: {}` | Correspond à chaque utilisateur authentifié. Commencez par l'un de ceux-ci et ajoutez des politiques limitées aux groupes au-dessus plus tard. |
560| `match: { groups: [a, b] }` | Correspond si la réclamation `groups` du JWT contient l'un des groupes listés. Sensible à la casse : les groupes doivent correspondre à la casse exacte de l'IdP. |579| `match: { groups: [a, b] }` | Correspond si la revendication `groups` du JWT contient l'un des groupes listés. Sensible à la casse : les groupes doivent correspondre à la casse exacte de l'IdP. |
561| `match: { email_domain: example.com }` | Correspond à la partie après le dernier `@` dans la réclamation `email` du JWT, insensible à la casse. Accepte un domaine par politique. |580| `match: { email_domain: example.com }` | Correspond à la partie après le dernier `@` dans la revendication `email` du JWT, insensible à la casse. Accepte un domaine par politique. |
562| `match: { groups: [a], email_domain: example.com }` | Les deux conditions doivent correspondre |581| `match: { groups: [a], email_domain: example.com }` | Les deux conditions doivent correspondre |
563 582
564Un utilisateur authentifié qui ne correspond à aucune politique obtient les valeurs par défaut de la passerelle, ce qui signifie chaque modèle du catalogue et aucun paramètre géré. Ajoutez une capture-tout `match: {}` en dernier si vous voulez une politique par défaut garantie.583Un utilisateur authentifié qui ne correspond à aucune politique obtient les valeurs par défaut de la passerelle, ce qui signifie chaque modèle du catalogue et aucun paramètre géré. Ajoutez une capture-tout `match: {}` en dernier si vous voulez une politique par défaut garantie.
565 584
566<Note>585<Note>
567 La passerelle ne garde aucun répertoire d'utilisateurs de son propre. Elle autorise chaque demande à partir du jeton IdP de l'utilisateur, en lisant l'appartenance au groupe à partir de la réclamation `groups` du jeton et en évaluant les politiques par rapport à celle-ci. Il n'y a pas de liste à énumérer et pas de comptes à pré-créer, et donc pas de point de terminaison SCIM, car il n'y a rien pour que SCIM se synchronise.586 La passerelle ne conserve aucun répertoire d'utilisateurs qui lui est propre. Elle autorise chaque demande à partir du jeton IdP de l'utilisateur, en lisant l'appartenance au groupe à partir de la revendication `groups` du jeton et en évaluant les politiques par rapport à celle-ci. Il n'y a pas de liste à énumérer et aucun compte à pré-créer, et donc aucun point de terminaison SCIM, car il n'y a rien pour que SCIM se synchronise.
568 587
569 Exécutez la gestion du cycle de vie des utilisateurs et des groupes à la source de vérité, qui est la mise en service SCIM native de votre IdP ou une plateforme de gouvernance d'identité dédiée. L'appartenance et la déprovision gouvernées là-bas s'écoulent dans la passerelle automatiquement via le jeton. Si vous voulez la mise en service SCIM des comptes Claude eux-mêmes, c'est une capacité [Claude for Enterprise](/docs/fr/admin-setup).588 Exécutez la gestion du cycle de vie des utilisateurs et des groupes à la source de vérité, qui est l'approvisionnement SCIM natif de votre IdP ou une plateforme de gouvernance des identités dédiée. L'appartenance et la déprovision gouvernées là-bas s'écoulent dans la passerelle automatiquement via le jeton. Si vous voulez l'approvisionnement SCIM des comptes Claude eux-mêmes, c'est une capacité [Claude for Enterprise](/docs/fr/admin-setup).
570 589
571 Deux horloges de propagation s'appliquent :590 Deux horloges de propagation s'appliquent :
572 591
573 * **Contenu de la politique** : éditer une politique et redéployer atteint les clients connectés lors de leur prochain sondage de paramètres gérés, dans une heure, à part les [changements qui s'appliquent uniquement au prochain lancement](/docs/fr/server-managed-settings#fetch-and-caching-behavior)592 * **Contenu de la politique** : modifier une politique et redéployer atteint les clients connectés lors de leur prochain sondage de paramètres gérés, dans une heure, à part les [modifications qui s'appliquent uniquement au prochain lancement](/docs/fr/server-managed-settings#fetch-and-caching-behavior)
574 * **Appartenance au groupe** : changer l'appartenance au groupe d'un utilisateur change quelle politique les correspond. Cela prend effet lors de la prochaine remise en monnaie de session, ce qui signifie le prochain rafraîchissement silencieux, limité par `session.ttl_hours`.593 * **Appartenance au groupe** : modifier l'appartenance au groupe d'un utilisateur change la politique qui le correspond. Cela prend effet lors du prochain renouvellement de session, ce qui signifie le prochain rafraîchissement silencieux, limité par `session.ttl_hours`.
575</Note>594</Note>
576 595
577<h4 id="matcher-values-that-stop-the-gateway-at-boot">596<h4 id="matcher-values-that-stop-the-gateway-at-boot">
583* Une liste `groups` vide602* Une liste `groups` vide
584* Une entrée vide dans `groups` ou dans `admin_groups`603* Une entrée vide dans `groups` ou dans `admin_groups`
585* Un `email_domain` vide604* Un `email_domain` vide
586* Un `email_domain` qui contient `@`, un espace blanc ou une virgule. La passerelle supprime la valeur et enlève un `@` initial avant cette vérification. Écrivez un domaine nu, tel que `example.com`.605* Un `email_domain` qui contient `@`, un espace blanc ou une virgule. La passerelle coupe la valeur et supprime un `@` initial avant cette vérification. Écrivez un domaine nu, comme `example.com`.
587 606
588Avant v2.1.232, la passerelle démarrait avec ces valeurs. Chaque valeur avait cet effet :607Avant v2.1.232, la passerelle démarrait avec ces valeurs. Chaque valeur avait cet effet :
589 608
590* Un `email_domain` vide : la passerelle a ignoré la vérification de domaine, donc une politique avec un `email_domain` vide et aucune liste `groups` correspondait à tous les utilisateurs authentifiés609* Un `email_domain` vide : la passerelle a ignoré la vérification du domaine, donc une politique avec un `email_domain` vide et aucune liste `groups` correspondait à chaque utilisateur authentifié
591* Une liste `groups` vide : la politique ne correspondait à personne610* Une liste `groups` vide : la politique ne correspondait à personne
592* Un `email_domain` contenant `@`, un espace blanc ou une virgule : la politique ne correspondait à personne611* Un `email_domain` contenant `@`, un espace blanc ou une virgule : la politique ne correspondait à personne
593* Une entrée vide dans `groups` ou dans `admin_groups` : l'entrée correspondait à un utilisateur uniquement lorsque la réclamation `groups` IdP de cet utilisateur contenait également une entrée vide. Dans `admin_groups`, cette correspondance accordait l'accès administrateur. Si votre liste `admin_groups` ne contenait jamais une entrée vide, personne n'a obtenu l'accès administrateur de cette façon.612* Une entrée vide dans `groups` ou dans `admin_groups` : l'entrée correspondait à un utilisateur uniquement lorsque la revendication `groups` IdP de cet utilisateur contenait également une entrée vide. Dans `admin_groups`, cette correspondance accordait l'accès admin. Si votre liste `admin_groups` ne contenait jamais une entrée vide, personne n'a obtenu l'accès admin de cette façon.
594 613
595<h4 id="what-goes-in-cli">614<h4 id="what-goes-in-cli">
596 Ce qui va dans `cli`615 Ce qui va dans `cli`
597</h4>616</h4>
598 617
599Chaque valeur `cli` est un document complet `managed-settings.json` de Claude Code, le même schéma que vous déploieriez via MDM ou `/etc/claude-code/managed-settings.json`, exprimé ici en YAML. Le CLI applique le document livré au niveau géré, au-dessus des paramètres utilisateur et projet, à la place des paramètres gérés par le serveur. Il ignore donc les paramètres [restreints aux sources de politique au niveau du système d'exploitation](/docs/fr/server-managed-settings#current-limitations), tels que `policyHelper` et `wslInheritsWindowsSettings`.618Chaque valeur `cli` est un document complet Claude Code `managed-settings.json`, le même schéma que vous déploieriez via MDM ou `/etc/claude-code/managed-settings.json`, exprimé ici en YAML. Le CLI applique le document livré au niveau géré, au-dessus des paramètres utilisateur et projet, à la place des paramètres gérés par le serveur. Il ignore donc les paramètres [restreints aux sources de politique au niveau du système d'exploitation](/docs/fr/server-managed-settings#current-limitations), comme `policyHelper` et `wslInheritsWindowsSettings`.
600 619
601La passerelle valide chaque document par rapport au schéma de paramètres du CLI au démarrage, donc une clé de niveau supérieur non reconnue échoue au démarrage avec une erreur nommant chaque clé offensante. Les parties délibérément ouvertes du schéma acceptent toujours des valeurs arbitraires, car les clients plus récents peuvent reconnaître les entrées que le schéma de la passerelle ne reconnaît pas. Ces clés ouvertes sont `env`, `pluginConfigs` et les clés imbriquées sous `permissions`.620La passerelle valide chaque document par rapport au schéma des paramètres du CLI au démarrage, donc une clé de niveau supérieur non reconnue échoue au démarrage avec une erreur nommant chaque clé contrevenante. Les parties délibérément ouvertes du schéma acceptent toujours des valeurs arbitraires, car les clients plus récents peuvent reconnaître des entrées que le schéma de la passerelle ne reconnaît pas. Ces clés ouvertes sont `env`, `pluginConfigs` et les clés imbriquées sous `permissions`.
602 621
603Parce que la validation utilise le schéma fourni avec la version installée de la passerelle, mettre une clé de paramètres de niveau supérieur introduite par une version plus récente de Claude Code dans la configuration gérée nécessite de mettre à niveau la passerelle en premier. Testez une nouvelle politique sur un client avant de la déployer largement.622Parce que la validation utilise le schéma fourni avec la version installée de la passerelle, placer une clé de paramètres de niveau supérieur introduite par une version plus récente de Claude Code dans la configuration gérée nécessite de mettre à niveau la passerelle en premier. Testez une nouvelle politique sur un client avant de la déployer.
604 623
605La référence de clé complète est dans [Paramètres Claude Code](/docs/fr/settings-reference#all-settings). Les clés que les opérateurs atteignent en premier :624La référence complète des clés se trouve dans [Paramètres Claude Code](/docs/fr/settings-reference#all-settings). Les clés que les opérateurs atteignent en premier :
606 625
607```yaml theme={null}626```yaml theme={null}
608managed:627managed:
618 - "WebFetch"637 - "WebFetch"
619 - "Read(./.env)"638 - "Read(./.env)"
620 - "Read(./secrets/**)"639 - "Read(./secrets/**)"
621 disableBypassPermissionsMode: disable # bloque --dangerously-skip-permissions640 disableBypassPermissionsMode: disable # blocks --dangerously-skip-permissions
622 allowManagedPermissionRulesOnly: true # ignorer les règles de permission utilisateur/projet641 allowManagedPermissionRulesOnly: true # ignore user/project permission rules
623 642
624 # Environnement poussé dans le processus CLI. DISABLE_UPDATES bloque643 # Environnement poussé dans le processus CLI. DISABLE_UPDATES bloque
625 # les mises à jour en arrière-plan et manuelles ; DISABLE_AUTOUPDATER arrête uniquement644 # les mises à jour en arrière-plan et manuelles ; DISABLE_AUTOUPDATER arrête uniquement
626 # les mises à jour en arrière-plan.645 # les mises à jour en arrière-plan.
627 env:646 env:
628 DISABLE_UPDATES: "1" # épingler les versions via votre propre distribution647 DISABLE_UPDATES: "1" # pin versions via your own distribution
629 648
630 # Hooks à l'échelle de l'organisation. Les commandes de hook s'exécutent sur les machines des développeurs, pas la649 # Hooks à l'échelle de l'organisation. Les commandes de hook s'exécutent sur les machines des développeurs, pas sur la
631 # passerelle, donc le chemin doit exister sur chaque système d'exploitation client dans la politique.650 # passerelle, donc le chemin doit exister sur chaque système d'exploitation client dans la politique.
632 hooks:651 hooks:
633 PostToolUse:652 PostToolUse:
637```656```
638 657
639| Clé | Appliquée par | Effet |658| Clé | Appliquée par | Effet |
640| ------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |659| ------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
641| `availableModels` | Passerelle + CLI | Liste d'autorisation de modèles. Également vérifiée à `/v1/messages`, donc un client patché ne peut pas la contourner. |660| `availableModels` | Passerelle + CLI | Liste d'autorisation des modèles. Également vérifiée à `/v1/messages`, donc un client corrigé ne peut pas la contourner. |
642| `permissions.allow` / `.deny` | CLI | Règles d'outils et de commandes. Voir [Permissions](/docs/fr/permissions). |661| `permissions.allow` / `.deny` | CLI | Règles d'outils et de commandes. Consultez [Permissions](/docs/fr/permissions). |
643| `permissions.disableBypassPermissionsMode` | CLI | Définissez sur `disable` pour bloquer [`bypassPermissions`](/docs/fr/permission-modes#skip-all-checks-with-bypasspermissions-mode), le mode qui approuve automatiquement chaque appel d'outil, et l'indicateur `--dangerously-skip-permissions` |662| `permissions.disableBypassPermissionsMode` | CLI | Définissez à `disable` pour bloquer [`bypassPermissions`](/docs/fr/permission-modes#skip-all-checks-with-bypasspermissions-mode), le mode qui ignore les invites de permission, et l'indicateur `--dangerously-skip-permissions` |
644| `allowManagedPermissionRulesOnly` | CLI | Lorsque `true`, les paramètres gérés deviennent la seule source de paramètres des règles de permission. L'entrée [`allowManagedPermissionRulesOnly`](/docs/fr/settings-reference#allowmanagedpermissionrulesonly) liste chaque source que Claude Code ignore ensuite. |663| `allowManagedPermissionRulesOnly` | CLI | Lorsque `true`, les paramètres gérés deviennent la seule source de paramètres des règles de permission. L'entrée [`allowManagedPermissionRulesOnly`](/docs/fr/settings-reference#allowmanagedpermissionrulesonly) liste chaque source que Claude Code ignore ensuite. |
645| `env` | CLI | Variables d'environnement fusionnées dans le processus CLI. Utilisez pour la télémétrie, la mise à jour automatique et les remplacements de noms de modèles. |664| `env` | CLI | Variables d'environnement fusionnées dans le processus CLI. Utilisez pour la télémétrie, la mise à jour automatique et les remplacements de noms de modèles. |
646| `hooks` | CLI | [Hooks](/docs/fr/hooks) à l'échelle de l'organisation |665| `hooks` | CLI | [Hooks](/docs/fr/hooks) à l'échelle de l'organisation |
666| `managedMcpServers` | CLI | Serveurs MCP distants [fournis à chaque développeur correspondant](/docs/fr/managed-mcp#provide-servers-through-managed-settings) aux côtés des serveurs qu'ils ajoutent eux-mêmes, `http` et `sse` uniquement. Consultez [Serveurs MCP dans une politique](#mcp-servers-in-a-policy). Nécessite Claude Code v2.1.259 ou ultérieur sur le serveur de passerelle et sur les clients. Les clients antérieurs ignorent la clé. |
647 667
648Parce que ces paramètres arrivent sur le réseau, le CLI affiche à chaque développeur un dialogue d'approbation de sécurité avant d'appliquer les paramètres listés ci-dessous :668Parce que ces paramètres arrivent sur le réseau, le CLI montre à chaque développeur une boîte de dialogue d'approbation de sécurité avant d'appliquer les paramètres listés ci-dessous :
649 669
650* `hooks`670* `hooks`
651* Variables `env` qui nécessitent l'approbation du développeur, telles que les variables de proxy et d'URL de base671* Variables `env` qui nécessitent l'approbation du développeur, comme les variables de proxy et d'URL de base
652* Paramètres d'exécution shell tels que `apiKeyHelper` et `statusLine`672* Paramètres d'exécution de shell comme `apiKeyHelper` et `statusLine`
653* les paramètres de binaire sandbox `sandbox.bwrapPath`, `sandbox.socatPath` et `sandbox.ripgrep`673* Les paramètres binaires du sandbox `sandbox.bwrapPath`, `sandbox.socatPath` et `sandbox.ripgrep`
654* Les paramètres Sandbox qui interceptent le trafic, injectent des identifiants ou affaiblissent l'isolation, tels que `sandbox.network.tlsTerminate` et les paramètres de port proxy. [Dialogues d'approbation de sécurité](/docs/fr/server-managed-settings#security-approval-dialogs) les liste tous.674* Les paramètres du sandbox qui interceptent le trafic, injectent des identifiants ou affaiblissent l'isolation, comme `sandbox.network.tlsTerminate` et les paramètres du port proxy. [Boîtes de dialogue d'approbation de sécurité](/docs/fr/server-managed-settings#security-approval-dialogs) les liste tous.
655 675
656[Mémoire d'approbation](/docs/fr/server-managed-settings#approval-memory) couvre combien de temps une approbation dure et quand le dialogue apparaît à nouveau.676[Mémoire d'approbation](/docs/fr/server-managed-settings#approval-memory) couvre la durée d'une approbation et quand la boîte de dialogue apparaît à nouveau.
657 677
658Claude Code applique certaines variables `env` livrées sans afficher le dialogue d'approbation au développeur, telles que les paramètres de sélection de modèle et les limites numériques. D'autres variables livrées peuvent nécessiter l'approbation du développeur avant de prendre effet ; une valeur de proxy non vide, d'URL de base ou `OTEL_EXPORTER_OTLP_ENDPOINT` le fait toujours. Lorsqu'une variable livrée a besoin d'approbation, le dialogue la nomme.678Claude Code applique certaines variables `env` livrées sans montrer la boîte de dialogue d'approbation au développeur, comme les paramètres de sélection de modèle et les limites numériques. D'autres variables livrées peuvent nécessiter l'approbation du développeur avant de prendre effet ; une valeur de proxy, d'URL de base ou `OTEL_EXPORTER_OTLP_ENDPOINT` non vide le fait toujours. Lorsqu'une variable livrée a besoin d'approbation, la boîte de dialogue la nomme.
659 679
660[Variables d'environnement et le dialogue d'approbation](/docs/fr/server-managed-settings#environment-variables-and-the-approval-dialog) a les détails, y compris quatre bascules de confidentialité dont la valeur livrée décide si elles ont besoin d'approbation. Avant v2.1.218, Claude Code appliquait moins de variables sans demander au développeur, donc plus de variables livrées déclenchaient le dialogue.680[Variables d'environnement et boîte de dialogue d'approbation](/docs/fr/server-managed-settings#environment-variables-and-the-approval-dialog) a les détails, y compris quatre bascules de confidentialité dont la valeur livrée décide si elles ont besoin d'approbation. Avant v2.1.218, Claude Code appliquait moins de variables sans demander au développeur, donc plus de variables livrées déclenchaient la boîte de dialogue.
661 681
662La configuration de [télémétrie](#telemetry) de la passerelle pousse `OTEL_EXPORTER_OTLP_ENDPOINT`, donc définir `telemetry.forward_to` déclenche le dialogue sur chaque client interactif. Le dialogue protège la machine du développeur d'une passerelle compromise ou hostile, pas l'organisation du développeur.682La configuration [télémétrie](#telemetry) de la passerelle pousse `OTEL_EXPORTER_OTLP_ENDPOINT`, donc définir `telemetry.forward_to` déclenche la boîte de dialogue sur chaque client interactif. La boîte de dialogue protège la machine du développeur d'une passerelle compromise ou hostile, pas l'organisation du développeur.
663 683
664Une exécution non interactive avec l'indicateur `-p` ne peut pas afficher le dialogue. Elle applique les paramètres poussés pour cette exécution uniquement et ne les enregistre pas comme approuvés, donc la prochaine session interactive du développeur affiche toujours le dialogue. Avant v2.1.207, une exécution non interactive enregistrait les paramètres comme approuvés et aucune session interactive ultérieure n'affichait le dialogue pour eux.684Une exécution non interactive avec l'indicateur `-p` ne peut pas montrer la boîte de dialogue. Elle applique les paramètres poussés pour cette exécution uniquement et ne les enregistre pas comme approuvés, donc la prochaine session interactive du développeur montre toujours la boîte de dialogue pour eux. Avant v2.1.207, une exécution non interactive enregistrait les paramètres comme approuvés et aucune session interactive ultérieure ne montrait la boîte de dialogue pour eux.
665 685
666Si un développeur refuse, Claude Code se termine plutôt que d'appliquer la politique. Lorsque vous poussez un nouveau hook, ou toute variable env qui déclenche le dialogue, vers une politique large, Claude Code affiche donc le dialogue à chaque développeur correspondant. Il affiche le dialogue dans une session en cours lors du prochain sondage horaire, et sinon au prochain démarrage du développeur.686Si un développeur refuse, Claude Code quitte cette session plutôt que d'appliquer la politique. Lorsque vous poussez un nouveau hook, ou toute variable env qui déclenche la boîte de dialogue, à une politique large, Claude Code montre donc la boîte de dialogue à chaque développeur correspondant. Il montre la boîte de dialogue dans une session en cours lors du prochain sondage horaire, et sinon au prochain démarrage du développeur.
667 687
668La clé `cli` s'appelait `settings` dans les versions antérieures. Cette orthographe est toujours acceptée comme alias, mais les nouveaux déploiements doivent utiliser `cli`.688La clé `cli` s'appelait `settings` dans les versions antérieures. Cette orthographe est toujours acceptée comme alias, mais les nouveaux déploiements doivent utiliser `cli`.
669 689
690<h4 id="mcp-servers-in-a-policy">
691 Serveurs MCP dans une politique
692</h4>
693
694Pour fournir des serveurs MCP aux clients Claude Code qu'une politique correspond, définissez [`managedMcpServers`](/docs/fr/managed-mcp#provide-servers-through-managed-settings) dans le bloc `cli` de cette politique. Vous avez besoin de Claude Code v2.1.259 ou ultérieur sur le serveur de passerelle et sur les clients.
695
696La passerelle vérifie chaque entrée au démarrage avec [les mêmes règles que Claude Code applique sur le client](/docs/fr/managed-mcp#what-an-entry-can-contain), et si une entrée échoue une vérification, la passerelle refuse de démarrer et nomme l'entrée.
697
698Si vous écrivez une référence `${VAR}` dans `gateway.yaml`, la passerelle la résout à partir de son environnement au démarrage via [expansion de secret](#secret-expansion) avant d'exécuter les vérifications d'entrée, donc chaque client correspondant reçoit la valeur littérale et peut la lire. [L'orientation d'en-tête pour les serveurs fournis](/docs/fr/managed-mcp#provide-servers-through-managed-settings) s'applique à la valeur étendue.
699
700La passerelle rejette l'orthographe `.mcp.json` `mcpServers` dans un bloc `cli`, et son erreur de démarrage nomme `managedMcpServers` comme clé à utiliser. Avant v2.1.259, la passerelle rejetait toute définition de serveur MCP dans un bloc `cli`.
701
670<h4 id="claude-desktop-overlay">702<h4 id="claude-desktop-overlay">
671 Superposition Claude Desktop703 Superposition Claude Desktop
672</h4>704</h4>
673 705
674Si votre organisation déploie également [Claude Desktop](/docs/fr/desktop), la même passerelle sert les deux clients. Pointez `bootstrapUrl`, dans la [configuration gérée](/docs/fr/desktop) de Claude Desktop, sur `<listen.public_url>/user/bootstrap`. Claude Desktop dérive l'émetteur OAuth de cette URL, exécute la même connexion par code d'appareil contre cette passerelle et récupère sa configuration à partir de la réponse.706Si votre organisation déploie également [Claude Desktop](/docs/fr/desktop), la même passerelle sert les deux clients. Pointez `bootstrapUrl`, dans la [configuration gérée](https://claude.com/docs/third-party/claude-desktop/configuration) de Claude Desktop, sur `<listen.public_url>/user/bootstrap`. Claude Desktop dérive l'émetteur OAuth de cette URL, exécute la même connexion par code d'appareil contre cette passerelle et récupère sa configuration à partir de la réponse.
675 707
676<Note>708<Note>
677 Nécessite Claude Code v2.1.203 ou ultérieur sur le serveur de passerelle, et un opt-in explicite : `/user/bootstrap` retourne 404 sauf si la politique correspondant à l'utilisateur porte une clé `desktop`. Un `desktop: {}` vide opte une politique, et une clé `desktop` sur la couche de base `match: {}` opte chaque politique qui l'hérite. Le journal d'audit enregistre chaque demande en tant que `desktop_bootstrap.serve` ou `desktop_bootstrap.denied`.709 Nécessite Claude Code v2.1.203 ou ultérieur sur le serveur de passerelle, et un opt-in explicite : `/user/bootstrap` retourne 404 sauf si la politique correspondant à l'utilisateur porte une clé `desktop`. Un `desktop: {}` vide opte une politique, et une clé `desktop` sur la couche de base `match: {}` opte chaque politique qui l'hérite. Le journal d'audit enregistre chaque demande en tant que `desktop_bootstrap.serve` ou `desktop_bootstrap.denied`.
679 711
680La passerelle dérive une grande partie de la réponse du bloc `cli` de la politique correspondante et de la configuration de passerelle de niveau supérieur :712La passerelle dérive une grande partie de la réponse du bloc `cli` de la politique correspondante et de la configuration de passerelle de niveau supérieur :
681 713
682* La liste de modèles, à partir de `availableModels`714* La liste des modèles, à partir de `availableModels`
683* Outils désactivés, à partir des entrées `permissions.deny` de nom d'outil nu. Si vous définissez `disabledBuiltinTools` dans le bloc `desktop` de la politique, la passerelle sert l'union de votre valeur et de la liste dérivée, donc vous pouvez désactiver plus d'outils de cette façon mais ne pouvez pas réactiver un que vous avez désactivé via `permissions.deny`715* Outils désactivés, à partir des entrées `permissions.deny` de nom d'outil nu. Si vous définissez `disabledBuiltinTools` dans le bloc `desktop` de la politique, la passerelle sert l'union de votre valeur et de la liste dérivée, afin que vous puissiez désactiver plus d'outils de cette façon mais ne pouvez pas réactiver un que vous avez désactivé via `permissions.deny`
684* La liste d'autorisation de sortie, à partir de `sandbox.network.allowedDomains`. Si vous définissez `coworkEgressAllowedHosts` dans le bloc `desktop` de la politique, la passerelle utilise cette valeur au lieu de la liste dérivée716* La liste d'autorisation de sortie, à partir de `sandbox.network.allowedDomains`. Si vous définissez `coworkEgressAllowedHosts` dans le bloc `desktop` de la politique, la passerelle utilise cette valeur à la place de la liste dérivée
685* Un point de terminaison OTLP qui pointe vers la passerelle elle-même, qui se distribue à vos destinations, inclus lorsque la transmission [`telemetry`](#telemetry) est configurée717* Un point de terminaison OTLP qui pointe vers la passerelle elle-même, et les attributs d'identité de l'utilisateur connecté. La passerelle relaie les exportations qu'elle reçoit à ce point de terminaison vers vos destinations `forward_to`. Elle inclut le point de terminaison et les attributs lorsque vous définissez à la fois [`telemetry.forward_to`](#telemetry) et `listen.public_url`.
718
719 Claude Desktop exporte chaque signal avec un encodage : `http/protobuf`, ou `http/json` lorsque vous définissez `OTEL_EXPORTER_OTLP_PROTOCOL` ou l'un de ses variantes par signal à `http/json` dans le `env` de la politique. Avant Claude Code v2.1.261 sur le serveur de passerelle, la réponse définissait `http/json` indépendamment, donc un collecteur qui accepte uniquement protobuf rejetait les exportations de Claude Desktop
686 720
687Pour définir `disabledBuiltinTools` ou `coworkEgressAllowedHosts` dans le bloc `desktop` d'une politique, vous avez besoin de Claude Code v2.1.232 ou ultérieur sur le serveur de passerelle.721Pour définir `disabledBuiltinTools`, `coworkEgressAllowedHosts` ou le paramètre `managedMcpServers` propre de Claude Desktop dans le bloc `desktop` d'une politique, vous avez besoin de Claude Code v2.1.232 ou ultérieur sur le serveur de passerelle. Le `managedMcpServers` de Claude Desktop prend une valeur de tableau plutôt qu'un objet.
688 722
689La passerelle omet les clés sans équivalent Claude Desktop, telles que `hooks` et les règles de permission limitées telles que `Bash(npm *)`, de la réponse bootstrap.723La passerelle omet les clés sans équivalent Claude Desktop, comme `hooks` et les règles de permission limitées comme `Bash(npm *)`, de la réponse d'amorçage.
690 724
691Ajoutez le bloc optionnel `desktop` à côté de `cli` pour définir les paramètres Claude Desktop directement. Écrivez les paramètres à partir de la [référence de configuration gérée](https://claude.com/docs/third-party/claude-desktop/configuration) de Claude Desktop en tant que noms de clé plats. Laissez de côté les clés que Claude Desktop lit uniquement à partir de MDM ou de fichiers locaux, telles que `bootstrapUrl` ; la passerelle les rejette au démarrage. Avant v2.1.232, la passerelle acceptait une liste fixe de 11 clés de porte de fonctionnalité, telles que `chatTabEnabled` et `disableAutoUpdates`, et rejetait chaque autre clé au démarrage. Avant v2.1.227, la passerelle rejetait également `chatTabEnabled` et `chatAdvancedFileAnalysisEnabled` au démarrage.725Ajoutez le bloc `desktop` optionnel aux côtés de `cli` pour définir les paramètres Claude Desktop directement. Écrivez les paramètres de la [référence de configuration gérée](https://claude.com/docs/third-party/claude-desktop/configuration) de Claude Desktop en tant que noms de clés plats. Laissez de côté les clés que Claude Desktop lit uniquement à partir de MDM ou de fichiers locaux, comme `bootstrapUrl` ; la passerelle les rejette au démarrage. Avant v2.1.232, la passerelle acceptait une liste fixe de 11 clés de porte de fonctionnalité, comme `chatTabEnabled` et `disableAutoUpdates`, et rejetait chaque autre clé au démarrage. Avant v2.1.227, la passerelle rejetait également `chatTabEnabled` et `chatAdvancedFileAnalysisEnabled` au démarrage.
692 726
693```yaml theme={null}727```yaml theme={null}
694managed:728managed:
705Chaque clé est optionnelle ; Claude Desktop applique sa propre valeur par défaut pour toute clé que vous omettez. La passerelle valide chaque bloc `desktop` au démarrage par rapport au schéma de configuration que Claude Desktop lui-même utilise, donc une erreur apparaît au démarrage de la passerelle en tant qu'erreur nommant la clé plutôt que d'atteindre chaque bureau connecté. La passerelle échoue au démarrage lorsqu'un bloc contient :739Chaque clé est optionnelle ; Claude Desktop applique sa propre valeur par défaut pour toute clé que vous omettez. La passerelle valide chaque bloc `desktop` au démarrage par rapport au schéma de configuration que Claude Desktop lui-même utilise, donc une erreur apparaît au démarrage de la passerelle en tant qu'erreur nommant la clé plutôt que d'atteindre chaque bureau connecté. La passerelle échoue au démarrage lorsqu'un bloc contient :
706 740
707* Une clé inconnue741* Une clé inconnue
708* Une clé reconnue dont la valeur que Claude Desktop rejetterait ou abandonnerait silencieusement, telle qu'une valeur vide ou une sous-clé mal orthographiée à l'intérieur d'une entrée imbriquée742* Une clé reconnue dont la valeur Claude Desktop rejetterait ou supprimerait silencieusement, comme une valeur vide ou une sous-clé mal orthographiée à l'intérieur d'une entrée imbriquée. Avant v2.1.260, la passerelle supprimait silencieusement un champ mal orthographié à l'intérieur d'un objet imbriqué d'une entrée `managedMcpServers` ou `orgPluginSettings` au lieu d'échouer au démarrage.
709* Une clé que la passerelle calcule elle-même : la connexion d'inférence, la liste de modèles et le relais OTLP. Configurez ceux-ci via [`upstreams`](#upstreams), [`models`](#models) et la section [`telemetry`](#telemetry) `forward_to`.743* Une clé que la passerelle calcule elle-même : la connexion d'inférence, la liste des modèles et le relais OTLP. Configurez ceux-ci via [`upstreams`](#upstreams), [`models`](#models) et la section [`telemetry`](#telemetry) `forward_to`.
710* Un alias hérité d'une clé actuelle. Dans l'erreur de démarrage, la passerelle nomme la clé canonique à écrire.744* Un alias hérité d'une clé actuelle. Dans l'erreur de démarrage, la passerelle nomme la clé canonique à écrire.
711 745
712Comme avec le bloc `cli`, la passerelle valide par rapport au schéma fourni avec sa version installée. Pour livrer un paramètre introduit par une version plus récente de Claude Desktop, mettez à niveau la passerelle en premier.746Si vous utilisez une valeur ou une forme d'entrée dépréciée, comme une entrée `managedMcpServers` sans `transport`, la passerelle démarre et enregistre un avertissement qui nomme le remplacement.
713 747
714La passerelle remplit les clés qu'un bloc `desktop` d'une politique ne définit pas à partir du bloc `desktop` de la capture-tout `match: {}`, de la même façon qu'elle remplit le bloc `cli` d'une politique à partir de la base. Si vous définissez `disabledBuiltinTools` ou `builtinToolPolicy` dans la base et une politique de rôle, la passerelle conserve la restriction de la base :748La passerelle valide un bloc `desktop` par rapport au schéma fourni avec sa version installée, comme elle le fait pour le bloc `cli`. Pour livrer un paramètre introduit par une version plus récente de Claude Desktop, mettez à niveau la passerelle en premier. Par exemple, `userPluginMarketplacesEnabled` et `userPluginUploadsEnabled` nécessitent Claude Code v2.1.260 ou ultérieur sur le serveur de passerelle et Claude Desktop 1.37937.0 ou ultérieur sur les machines des membres.
749
750Si vous définissez `orgPluginSettings` dans le bloc `desktop` d'une politique, la passerelle le sert sous la forme de tableau que Claude Desktop 1.15200.0 et ultérieur lit. Les anciens bureaux ignorent le tableau et n'appliquent aucune politique d'outil de plugin, donc mettez à jour les membres à 1.15200.0 ou ultérieur avant de vous y fier.
751
752La passerelle remplit les clés qu'un bloc `desktop` de politique ne définit pas à partir du bloc `desktop` de la capture-tout `match: {}`, de la même manière qu'elle remplit le bloc `cli` d'une politique à partir de la base. Si vous définissez `disabledBuiltinTools` ou `builtinToolPolicy` à la fois dans la base et dans une politique par rôle, la passerelle conserve la restriction de la base :
715 753
716* `disabledBuiltinTools` : la passerelle utilise l'union de la liste de la base et de la liste de la politique754* `disabledBuiltinTools` : la passerelle utilise l'union de la liste de la base et de la liste de la politique
717* `builtinToolPolicy` : si vous définissez un outil à une valeur autre que `allow` dans la base, la passerelle conserve cette valeur même si vous définissez `allow` pour le même outil dans une politique de rôle755* `builtinToolPolicy` : si vous définissez un outil à une valeur autre que `allow` dans la base, la passerelle conserve cette valeur même si vous définissez `allow` pour le même outil dans une politique par rôle
718 756
719Pour chaque autre clé, si vous la définissez dans la politique de rôle, la passerelle utilise la valeur de la politique de rôle. La passerelle remplace un tableau ou un objet imbriqué tel que `banner` en entier, donc si vous définissez `banner.text` dans une politique de rôle, la passerelle abandonne le `banner.backgroundColor` de la base.757Pour chaque autre clé, si vous la définissez dans la politique par rôle, la passerelle utilise la valeur de la politique par rôle. La passerelle remplace un tableau ou un objet imbriqué comme `banner` entièrement, donc si vous définissez `banner.text` dans une politique par rôle, la passerelle supprime le `banner.backgroundColor` de la base.
720 758
721Si vous ne déployez pas Claude Desktop, laissez `desktop` complètement hors de vos politiques ; la passerelle retourne alors 404 de `/user/bootstrap` pour chaque utilisateur.759Si vous ne déployez pas Claude Desktop, laissez `desktop` complètement hors de vos politiques ; la passerelle retourne alors 404 à partir de `/user/bootstrap` pour chaque utilisateur.
722 760
723<h4 id="precedence-with-other-managed-sources">761<h4 id="precedence-with-other-managed-sources">
724 Précédence avec d'autres sources gérées762 Précédence avec d'autres sources gérées
725</h4>763</h4>
726 764
727Si un appareil a également une politique livrée par MDM ou une `managed-settings.json` locale, les paramètres livrés par la passerelle sont classés en premier. [Précédence au sein de la couche gérée](/docs/fr/managed-settings#precedence-within-the-managed-tier) sur la page des paramètres gérés dit quand les sources locales s'appliquent, et a les [clés que Claude Code lit à partir de chaque source admin](/docs/fr/managed-settings#keys-read-from-every-admin-source) indépendamment de la source qu'il a sélectionnée, telles que les clés de verrouillage sandbox, `forceRemoteSettingsRefresh` et la fusion `env` par variable. Un [`policyHelper`](/docs/fr/settings-reference#policyhelper) configuré dans un profil MDM ou le fichier de paramètres gérés s'exécute uniquement lorsque la passerelle ne livre aucun paramètre ; l'entrée dit ce que sa sortie remplace.765Si un appareil a également une politique livrée par MDM ou un `managed-settings.json` local, les paramètres livrés par la passerelle sont classés en premier. [Précédence au sein du niveau géré](/docs/fr/managed-settings#precedence-within-the-managed-tier) sur la page des paramètres gérés dit quand les sources locales s'appliquent, et a les [clés que Claude Code lit à partir de chaque source admin](/docs/fr/managed-settings#keys-read-from-every-admin-source) indépendamment de la source qu'il a sélectionnée, comme les clés de verrouillage du sandbox, `forceRemoteSettingsRefresh` et le `env` par variable. Un [`policyHelper`](/docs/fr/settings-reference#policyhelper) configuré dans un profil MDM ou le fichier des paramètres gérés s'exécute uniquement lorsque la passerelle ne livre aucun paramètre ; l'entrée dit ce que sa sortie remplace.
728 766
729Les hôtes d'intégration tels que [Claude Desktop](/docs/fr/desktop) peuvent fournir une politique via l'option SDK `managedSettings`. [Paramètres parents à partir d'hôtes d'intégration](/docs/fr/managed-settings#parent-settings-from-embedding-hosts) dit quand Claude Code l'applique, et [Restreindre les paramètres parents](/docs/fr/claude-apps-gateway#restrict-parent-settings) liste lesquels les paramètres de direction d'autorisation s'appliquent toujours sans les verrous `allowManaged*Only`.767Les hôtes d'intégration comme [Claude Desktop](/docs/fr/desktop) peuvent fournir une politique via l'option SDK `managedSettings`. [Paramètres parents à partir d'hôtes d'intégration](/docs/fr/managed-settings#parent-settings-from-embedding-hosts) dit quand Claude Code l'applique, et [Restreindre les paramètres parents](/docs/fr/claude-apps-gateway#restrict-parent-settings) liste les paramètres de direction d'autorisation qui s'appliquent toujours sans les verrous `allowManaged*Only`.
730 768
731Les politiques de passerelle s'appliquent à chaque invocation de Claude Code sur la machine, y compris les exécutions non interactives `claude -p` et les sessions générées par le SDK Agent. Si la passerelle est inaccessible au démarrage, les sessions signées se terminent avec une erreur plutôt que de s'exécuter sans leur politique.769Les politiques de passerelle s'appliquent à chaque invocation de Claude Code sur la machine, y compris les exécutions non interactives `claude -p` et les sessions générées par le SDK Agent. Si la passerelle est inaccessible au démarrage, les sessions connectées quittent avec une erreur plutôt que de s'exécuter sans leur politique.
732
733<Warning>
734 Au démarrage, la passerelle rejette `mcpServers` à l'intérieur du bloc `cli` d'une politique. Vous ne pouvez pas distribuer les serveurs MCP par groupe aux clients Claude Code ; déployez les serveurs MCP via le `managed-mcp.json` basé sur fichier sur chaque appareil ou laissez les développeurs les ajouter localement. Vous pouvez livrer le paramètre `managedMcpServers` de Claude Desktop aux clients Claude Desktop via le bloc `desktop` d'une politique. Pour le définir, vous avez besoin de Claude Code v2.1.232 ou ultérieur sur le serveur de passerelle.
735</Warning>
736 770
737<h3 id="telemetry">771<h3 id="telemetry">
738 `telemetry`772 `telemetry`
739</h3>773</h3>
740 774
741Le CLI envoie le protocole OpenTelemetry (OTLP) sur les métriques, journaux et, lorsqu'ils sont activés, les traces HTTP à la passerelle, qui les relaye textuellement à chaque destination configurée. Voir [Surveillance de l'utilisation](/docs/fr/monitoring-usage) pour les métriques et événements que le CLI émet.775Le CLI envoie des métriques, des journaux et, lorsqu'ils sont activés, des traces à la passerelle, qui les relaie textuellement à chaque destination configurée. Les exportations utilisent OpenTelemetry Protocol (OTLP) sur HTTP. Pour ignorer le relais et faire exporter les sessions directement vers votre collecteur, [nommez le collecteur dans une politique](#export-directly-to-your-collector). Consultez [Surveillance de l'utilisation](/docs/fr/monitoring-usage) pour les métriques et événements que le CLI émet.
776
777Le CLI horodate chaque exportation avec l'identité de l'utilisateur authentifié, lue à partir du JWT émis par la passerelle : les attributs `user.id`, `user.email` et `user.groups`. L'attribution du coût et de l'utilisation par développeur fonctionne donc sans configuration côté développeur.
778
779[Claude Desktop](#claude-desktop-overlay) et les sessions Cowork connectées via la passerelle horodatent leur télémétrie avec `user.email` et `user.groups` aux côtés de `enduser.id`, afin que vous puissiez couvrir l'utilisation du terminal, du Bureau et de Cowork avec une requête sur `user.email` ou `user.groups`. `user.groups` est la liste des groupes IdP séparée par des virgules.
780
781Comme toutes les données OpenTelemetry de Claude Code, ces attributs vont uniquement aux destinations que votre organisation configure, jamais à Anthropic.
742 782
743Le CLI horodate chaque export avec l'identité de l'utilisateur authentifié, lue à partir du JWT émis par la passerelle : les attributs `user.id`, `user.email` et `user.groups`. L'attribution du coût et de l'utilisation par développeur fonctionne donc sans aucune configuration côté développeur.783Si la liste de groupes d'un utilisateur dépasse 255 caractères une fois codée en pourcentage, ou si un nom de groupe contient une virgule ou un signe égal, la passerelle laisse `user.groups` hors de la télémétrie Desktop et Cowork de cet utilisateur plutôt que de la tronquer. Les sessions de terminal de cet utilisateur portent toujours la liste complète.
784
785Vous avez besoin de Claude Code v2.1.265 ou ultérieur sur le serveur de passerelle pour `user.email` et `user.groups` sur la télémétrie Desktop et Cowork, et Claude Desktop 1.24012 ou ultérieur sur la machine de chaque développeur pour `user.groups`.
744 786
745```yaml theme={null}787```yaml theme={null}
746telemetry:788telemetry:
760<Warning>802<Warning>
761 Chaque destination opte pour `metrics`, `logs` et `traces` indépendamment, et la valeur par défaut est les métriques uniquement. Les signaux diffèrent en sensibilité :803 Chaque destination opte pour `metrics`, `logs` et `traces` indépendamment, et la valeur par défaut est les métriques uniquement. Les signaux diffèrent en sensibilité :
762 804
763 * **Métriques** : compteurs agrégés tels que les comptages de jetons, les comptages de demandes et la latence805 * **Métriques** : compteurs agrégés comme les comptages de jetons, les comptages de demandes et la latence
764 * **Journaux et traces** : peuvent porter des commandes bash complètes, des entrées d'outils et des chemins de fichiers, couvrant tout ce que Claude Code fait sur la machine d'un développeur806 * **Journaux et traces** : peuvent porter des commandes bash complètes, des entrées d'outils et des chemins de fichiers, couvrant tout ce que Claude Code fait sur la machine d'un développeur
765 807
766 Activez les journaux et les traces uniquement sur les destinations avec les contrôles d'accès et la politique de rétention que les données justifient.808 Activez les journaux et les traces uniquement sur les destinations avec les contrôles d'accès et la politique de rétention que les données justifient.
767</Warning>809</Warning>
768 810
769Chaque URL `forward_to` doit utiliser `https://`, avec une exception pour un collecteur sur l'interface loopback de la passerelle elle-même :811Chaque URL `forward_to` doit utiliser `https://`, avec une exception pour un collecteur sur l'interface de bouclage de la passerelle elle-même :
770 812
771* `http://localhost:<port>` passe la validation de configuration, mais la [garde SSRF](/docs/fr/claude-apps-gateway-deploy#threat-model-summary) bloque chaque export avec `ECONNREFUSED_SSRF` sauf si vous définissez `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` dans l'environnement de la passerelle813* `http://localhost:<port>` passe la validation de configuration, mais la [garde SSRF](/docs/fr/claude-apps-gateway-deploy#threat-model-summary) bloque chaque exportation avec `ECONNREFUSED_SSRF` sauf si vous définissez `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` dans l'environnement de la passerelle
772* `http://127.0.0.1:<port>` ou `http://[::1]:<port>` échoue au démarrage sauf si cette variable est définie814* `http://127.0.0.1:<port>` ou `http://[::1]:<port>` échoue au démarrage sauf si cette variable est définie
773 815
774Pour un collecteur en cluster, exposez-le sur HTTPS à sa propre adresse interne, ou exécutez-le en tant que sidecar avec la variable définie.816Pour un collecteur en cluster, exposez-le sur HTTPS à sa propre adresse interne, ou exécutez-le en tant que sidecar avec la variable définie.
775 817
776La télémétrie est désactivée dans le CLI par défaut. Configurer `telemetry.forward_to` avec `listen.public_url` l'active. La passerelle pousse six variables env à chaque client connecté via `/managed/settings` :818La télémétrie est désactivée dans le CLI par défaut. Lorsque vous définissez à la fois `telemetry.forward_to` et `listen.public_url`, la passerelle l'active pour les clients connectés en poussant six variables d'environnement via `/managed/settings` :
777 819
778* `CLAUDE_CODE_ENABLE_TELEMETRY=1`820* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
779* `OTEL_METRICS_EXPORTER=otlp`821* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` et `OTEL_TRACES_EXPORTER`, chacun défini à `otlp` si au moins une destination `forward_to` active ce signal et à `none` sinon
780* `OTEL_LOGS_EXPORTER=otlp`
781* `OTEL_TRACES_EXPORTER=otlp`
782* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`822* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`
783* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`823* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`
784 824
785Le point de terminaison poussé est construit à partir de l'URL publique, donc les métriques et les journaux n'ont besoin d'aucune configuration OTEL des développeurs ou des politiques. La configuration poussée est appliquée au niveau géré, remplaçant les variables `OTEL_*` qu'un développeur définit localement. Que la passerelle pousse ou non ces variables, un CLI signé via `/login` qui a l'export OTLP/HTTP activé envoie ses exports à la passerelle plutôt qu'à un point de terminaison configuré localement, et sans destination `forward_to` pour un signal la passerelle accepte et l'abandonne ; si vous collectez déjà la télémétrie Claude Code directement, ajoutez votre collecteur en tant que destination `forward_to`.825Avant Claude Code v2.1.265 sur le serveur de passerelle, la passerelle poussait les trois sélecteurs d'exportateur en tant que `otlp`, y compris pour les signaux qu'aucune destination n'a activés.
826
827Le point de terminaison poussé est construit à partir de l'URL publique, donc les métriques et les journaux n'ont besoin d'aucune configuration OTEL de la part des développeurs ou des politiques.
828
829Les développeurs connectés via `/login` ne peuvent pas rediriger les exportations avec leur propre configuration OTEL :
830
831* **Variables définies localement** : Claude Code applique les variables poussées au niveau géré, donc chacune remplace la valeur qu'un développeur définit pour elle localement.
832* **Points de terminaison configurés localement** : avec l'exportation OTLP/HTTP activée, le CLI ignore tout point de terminaison configuré localement, que la passerelle ait poussé les variables de télémétrie ou non. Ses exportations vont à la passerelle sauf si une politique [nomme votre collecteur comme point de terminaison](#export-directly-to-your-collector).
833
834Sans destination `forward_to` pour un signal, la passerelle l'accepte et le rejette. Si les développeurs exportent déjà la télémétrie Claude Code vers l'un de vos collecteurs, ajoutez-le en tant que destination `forward_to`, avec les journaux ou les traces activés s'ils les exportent, afin qu'il continue à recevoir leurs données après qu'ils se connectent. Pour ignorer le relais à la place, [nommez le collecteur dans une politique](#export-directly-to-your-collector).
835
836[Les traces](/docs/fr/monitoring-usage#traces-beta) nécessitent également `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` sur chaque client. Définissez-le dans le bloc `env` d'une politique gérée, car la passerelle ne le pousse pas. Les développeurs l'approuvent dans la même [boîte de dialogue d'approbation de sécurité](#managed) que le point de terminaison poussé déclenche déjà.
786 837
787[Les traces](/docs/fr/monitoring-usage#traces-beta) nécessitent en outre `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` sur chaque client. La passerelle ne pousse pas cette variable, donc définissez-la via le bloc `env` d'une politique gérée. Ce n'est pas parmi les variables que Claude Code applique sans l'approbation du développeur, donc la livrer via une politique est couverte par le même [dialogue d'approbation de sécurité](#managed) que le point de terminaison OTLP poussé déclenche déjà.838Définissez-le à `1` uniquement dans les politiques dont vous voulez que les groupes soient tracés. Une politique qui ne le définit pas hérite la valeur de votre politique de capture-tout `match: {}` si cette politique en définit une, selon les [règles de fusion](#managed). Pour empêcher les clients d'un groupe d'envoyer des traces même lorsqu'un développeur définit la variable localement, définissez-la à `0` dans la politique de ce groupe.
788 839
789Les encodages OTLP protobuf et JSON sont relayés, et tout backend compatible OpenTelemetry fonctionne comme destination.840Les encodages OTLP protobuf et JSON sont relayés, et tout backend compatible OpenTelemetry fonctionne comme destination.
790 841
842<h4 id="export-directly-to-your-collector">
843 Exporter directement vers votre collecteur
844</h4>
845
846Pour faire envoyer les sessions connectées via `/login` la télémétrie directement à votre collecteur au lieu de passer par le relais, définissez `OTEL_EXPORTER_OTLP_ENDPOINT` à l'URL de base `https://` du collecteur dans le bloc `env` d'une [politique gérée](#managed). Claude Code ajoute `/v1/metrics`, `/v1/logs` ou `/v1/traces` à l'URL que vous définissez, comme `https://otel-collector.example.com:4318`, et exporte chaque signal là-bas sur OTLP/HTTP. Nécessite Claude Code v2.1.265 ou ultérieur sur la machine de chaque développeur. Les clients antérieurs exportent via le relais.
847
848Pour vous authentifier auprès du collecteur, définissez `OTEL_EXPORTER_OTLP_HEADERS` dans le même bloc `env`. Les sessions n'envoient jamais le jeton de session de passerelle du développeur à un collecteur nommé de cette façon.
849
850Lorsque vous ajoutez ou modifiez ce point de terminaison dans une politique, Claude Code demande à chaque développeur de l'approuver dans la [boîte de dialogue d'approbation de sécurité](#managed) avant de l'appliquer dans une session interactive.
851
852Claude Code vérifie le point de terminaison avant d'exporter un signal directement, et garde ce signal sur le relais lorsqu'une vérification échoue. Les vérifications incluent :
853
854* Le point de terminaison provient de la passerelle elle-même. Si vous définissez la même variable dans un profil MDM ou un `managed-settings.json` local, les exportations restent sur le relais.
855* L'URL utilise `https://`, ou `http://` vers une adresse de bouclage
856* L'URL se résout en un chemin se terminant par `/v1/<signal>`, sans requête ni fragment. Claude Code construit ce chemin lui-même à partir de la variable générique. Il utilise une variable par signal comme `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` telle qu'écrite, donc incluez le chemin complet là-bas.
857* L'URL n'est pas l'hôte de la passerelle elle-même. Un point de terminaison adressé à la passerelle conserve le chemin du relais et son jeton de session.
858* Ni vous ni le développeur n'avez configuré [`otelHeadersHelper`](/docs/fr/settings-reference#otelheadershelper) dans aucune source de paramètres. Avec un helper configuré, chaque signal reste sur le relais.
859
860Le point de terminaison que vous nommez change uniquement où les exportations vont. Vous choisissez toujours quels signaux exportent du tout avec les sélecteurs `OTEL_*_EXPORTER`.
861
862Le point de terminaison seul n'active pas l'exportation, donc définissez également les variables qui le font, sauf si la passerelle les pousse déjà :
863
864* Si la passerelle [pousse déjà les variables de télémétrie](#telemetry), elles couvrent l'activation, les sélecteurs et le protocole, et votre point de terminaison explicite remplace la valeur `<public_url>` poussée. Définissez un sélecteur `OTEL_*_EXPORTER` à `otlp` vous-même uniquement pour un signal qu'aucune destination `forward_to` n'active.
865* Si ce n'est pas le cas, définissez également `CLAUDE_CODE_ENABLE_TELEMETRY=1`, les sélecteurs `OTEL_*_EXPORTER` et `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`.
866
867Lorsque le développeur se déconnecte, ou se connecte à une passerelle différente, les exportations vers le collecteur s'arrêtent et Claude Code rejette chaque lot restant plutôt que de l'envoyer.
868
869<h4 id="when-a-destination-fails">
870 Lorsqu'une destination échoue
871</h4>
872
873La passerelle ne met pas en mémoire tampon, ne réessaie pas ou ne stocke pas la télémétrie, donc elle rejette une exportation qui n'atteint pas une destination plutôt que de la livrer tard. Chaque destination réussit ou échoue par elle-même, et le client exportateur reçoit une réponse de succès de toute façon, donc une livraison échouée n'apparaît que dans le journal de la passerelle.
874
875Après cinq livraisons consécutives échouées à une destination, la passerelle met en pause le transfert vers elle en étirements de 30 secondes, enregistrant chaque pause, jusqu'à ce qu'une livraison réussisse. Toute réponse d'erreur, délai d'attente ou erreur de connexion compte comme une livraison échouée, sauf `400`, `413`, `415`, `422` et `431`, qui signifient que le collecteur a refusé la charge utile de cette exportation comme mal formée ou trop grande.
876
877Une charge utile refusée n'avance ni ne réinitialise le compteur d'échecs : la passerelle continue de transférer vers la destination et enregistre un avertissement nommant celle-ci et le statut, au premier refus de la destination et tous les centièmes après.
878
791<h3 id="http-tuning">879<h3 id="http-tuning">
792 Réglage HTTP880 Réglage HTTP
793</h3>881</h3>
794 882
795Quatre blocs optionnels de niveau supérieur, `access_control`, `limits`, `timeouts` et `rate_limits`, ajustent la surface HTTP. Les valeurs par défaut conviennent à la plupart des déploiements.883Quatre blocs optionnels de niveau supérieur, `access_control`, `limits`, `timeouts` et `rate_limits`, règlent la surface HTTP. Les valeurs par défaut conviennent à la plupart des déploiements.
796 884
797| Bloc | Clé | Par défaut | Description |885| Bloc | Clé | Par défaut | Description |
798| ---------------- | ---------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |886| ---------------- | ---------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
799| `access_control` | `allow_cidrs` / `deny_cidrs` | vide | Autorisation/refus IP entrant par adresse client, après résolution `trusted_proxies`. `deny_cidrs` est vérifié en premier ; un client qu'il correspond est rejeté même si `allow_cidrs` correspond également. Si `allow_cidrs` est non vide, la passerelle est par défaut refusée. `/healthz` et `/readyz` sont exempts de `allow_cidrs`. |887| `access_control` | `allow_cidrs` / `deny_cidrs` | vide | Autorisation/refus IP entrant par adresse client, après résolution `trusted_proxies`. `deny_cidrs` est vérifié en premier ; un client qu'il correspond est rejeté même si `allow_cidrs` correspond également. Si `allow_cidrs` est non vide, la passerelle est par défaut refusée. `/healthz` et `/readyz` sont exempts de `allow_cidrs`. Lorsqu'un proxy de confiance envoie une entrée `X-Forwarded-For` qui n'est pas une adresse IP, le vrai client est inconnu et la passerelle enregistre un avertissement une fois nommant ce qu'il faut vérifier. Où l'une ou l'autre liste s'applique à la demande, elle la refuse avec `403` et la raison d'audit `xff_unparseable`. Où aucune ne s'applique, elle sert la demande et utilise l'adresse du proxy lui-même comme IP client pour les limites de débit par IP et l'audit. |
800| `limits` | `max_request_bytes` | 32 MiB | Corps de demande entrant max ; les demandes surdimensionnées obtiennent `413` avant que le corps soit mis en mémoire tampon. Augmentez pour les demandes de fichiers ou d'images volumineux. |888| `limits` | `max_request_bytes` | 32 MiB | Corps de demande entrant max ; les demandes surdimensionnées obtiennent `413` avant que le corps ne soit mis en mémoire tampon. Augmentez pour les demandes de fichiers ou d'images volumineux. |
801| `limits` | `max_request_header_bytes` | non défini | Lorsqu'il est défini, les en-têtes surdimensionnés retournent `431` |889| `limits` | `max_request_header_bytes` | non défini | Lorsqu'il est défini, les en-têtes surdimensionnés retournent `431` |
802| `limits` | `max_url_length` | non défini | Lorsqu'il est défini, une URL trop longue retourne `414` |890| `limits` | `max_url_length` | non défini | Lorsqu'il est défini, une URL trop longue retourne `414` |
803| `timeouts` | `upstream_ttfb_ms` | 120000 | Attente max pour les en-têtes de réponse upstream (time to first byte). Le corps de la réponse s'écoule ensuite sans plafond de temps mural. S'applique au chemin upstream Anthropic direct ; chaque autre fournisseur est limité par le timeout du SDK du fournisseur. |891| `timeouts` | `upstream_ttfb_ms` | 120000 | Attente max pour les en-têtes de réponse en amont (temps jusqu'au premier octet). Le corps de la réponse s'écoule ensuite sans plafond mural. S'applique au chemin d'amont Anthropic direct ; chaque autre fournisseur est limité par le délai d'attente propre du SDK du fournisseur. |
804| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Limite de débit par IP sur le point de terminaison d'autorisation d'appareil non authentifié. Augmentez pour une grande organisation derrière une IP de sortie partagée ou NAT. Ces limites s'appliquent uniquement au flux de connexion de subvention d'appareil, pas à l'inférence `/v1/messages`. Voir [Résistance à la force brute du code utilisateur](/docs/fr/claude-apps-gateway-deploy#user-code-brute-force-resistance). |892| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Limite de débit par IP sur le point de terminaison d'autorisation d'appareil non authentifié. Augmentez pour une grande organisation derrière une adresse IP de sortie partagée ou NAT. Ces limites s'appliquent uniquement au flux de connexion par octroi d'appareil, pas à l'inférence `/v1/messages`. Consultez [Résistance à la force brute du code utilisateur](/docs/fr/claude-apps-gateway-deploy#user-code-brute-force-resistance). |
805| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Limite de débit par IP sur les soumissions `user_code` à `/device` |893| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Limite de débit par IP sur les soumissions `user_code` à `/device` |
806 894
807<h2 id="complete-example">895<h2 id="complete-example">
808 Exemple complet896 Exemple complet
809</h2>897</h2>
810 898
811Cette configuration de référence complète exerce chaque section principale ; les blocs de [réglage HTTP](#http-tuning) gardent leurs valeurs par défaut. Copiez-la, supprimez ce dont vous n'avez pas besoin et remplissez vos valeurs. La configuration du [démarrage rapide](/docs/fr/claude-apps-gateway#quickstart) est une version minimale de celle-ci.899Cette configuration de référence complète exerce chaque section centrale ; les [blocs de tuning HTTP](#http-tuning) conservent leurs valeurs par défaut. Copiez-la, supprimez ce dont vous n'avez pas besoin, et remplissez vos valeurs. La configuration dans le [Démarrage rapide](/docs/fr/claude-apps-gateway#quickstart) est une version minimale de celle-ci.
812 900
813```yaml gateway.yaml theme={null}901```yaml gateway.yaml theme={null}
814# Exécuter avec :902# Exécutez avec :
815# claude gateway --config gateway.yaml903# claude gateway --config gateway.yaml
816#904#
817# La verbosité du journal opérationnel est contrôlée par la variable d'environnement905# La verbosité du journal opérationnel est contrôlée par la variable
818# CLAUDE_GATEWAY_LOG_LEVEL (debug | info | warn | error ; par défaut info). debug906# d'environnement CLAUDE_GATEWAY_LOG_LEVEL
907# (debug | info | warn | error ; par défaut info). debug
819# enregistre également les noms de réclamations dans chaque id_token, pour le diagnostic de groups_claim.908# enregistre également les noms de réclamations dans chaque id_token, pour le diagnostic de groups_claim.
820# Cela n'affecte pas les événements d'audit, qui sont toujours émis.909# Cela n'affecte pas les événements d'audit, qui sont toujours émis.
821 910
823 host: 0.0.0.0912 host: 0.0.0.0
824 port: 8080913 port: 8080
825 public_url: https://claude-gateway.internal.example.com914 public_url: https://claude-gateway.internal.example.com
826 # Omettez le bloc tls lors de l'exécution derrière une entrée terminant TLS.915 # Omettez le bloc tls lors de l'exécution derrière une entrée qui termine TLS.
827 # tls:916 # tls:
828 # cert: /certs/gateway.crt917 # cert: /certs/gateway.crt
829 # key: /certs/gateway.key918 # key: /certs/gateway.key
836 client_secret: ${OIDC_CLIENT_SECRET}925 client_secret: ${OIDC_CLIENT_SECRET}
837 allowed_email_domains:926 allowed_email_domains:
838 - example.com927 - example.com
839 # Requis lorsque l'émetteur est le serveur org Okta, dont les id_tokens928 # Requis lorsque l'émetteur est le serveur d'organisation Okta, dont les id_tokens
840 # peuvent omettre l'e-mail et les groupes ; la passerelle les remplit à partir de /userinfo.929 # peuvent omettre l'e-mail et les groupes ; la passerelle les remplit à partir de /userinfo.
841 userinfo_fallback: true930 userinfo_fallback: true
842 # allowed_groups: [claude-code-users]931 # allowed_groups: [claude-code-users]
843 # Okta émet les groupes uniquement lorsque la portée `groups` est demandée et que932 # Okta émet des groupes uniquement lorsque la portée `groups` est demandée et que
844 # le filtre de réclamation de groupes de l'application les autorise. La politique des entrepreneurs ci-dessous933 # le filtre de réclamation de groupes de l'application les autorise. La politique
845 # correspond sur les groupes, donc la portée est demandée ici.934 # des entrepreneurs ci-dessous correspond aux groupes, donc la portée est demandée ici.
846 scopes: [openid, profile, email, offline_access, groups]935 scopes: [openid, profile, email, offline_access, groups]
847 # extra_auth_params: { access_type: offline, prompt: consent } # Google936 # extra_auth_params: { access_type: offline, prompt: consent } # Google
848 # groups_claim: groups # Rôles d'application Entra : utiliser `roles`937 # groups_claim: groups # Rôles d'application Entra : utilisez `roles`
849 # email_claim: email938 # email_claim: email
850 939
851session:940session:
857 # max_connections: 5946 # max_connections: 5
858 947
859# Active /v1/organizations/spend_limits (reflète l'API Admin Anthropic)948# Active /v1/organizations/spend_limits (reflète l'API Admin Anthropic)
860# et l'application de dépenses par développeur sur /v1/messages. Omettez pour désactiver.949# et l'application des limites de dépenses par développeur sur /v1/messages. Omettez pour désactiver.
861# Les plafonds eux-mêmes sont définis via l'API admin, pas ici.950# Les plafonds eux-mêmes sont définis via l'API admin, pas ici.
862# admin:951# admin:
863# write_keys:952# write_keys:
865# read_keys:954# read_keys:
866# - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }955# - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
867# admin_groups: [platform-finops]956# admin_groups: [platform-finops]
868# blocked_message: demander une augmentation à https://go.example.com/claude-limits957# blocked_message: request an increase at https://go.example.com/claude-limits
869# # audit_retention_days: 365958# # audit_retention_days: 365
870# # spend_retention_months: 13959# # spend_retention_months: 13
871# # identity_retention_days: 90960# # identity_retention_days: 90
874# enforcement:963# enforcement:
875# fail_closed_on_error: false964# fail_closed_on_error: false
876 965
877# Mesurez aux tarifs contractuels au lieu du prix catalogue USD. Nécessite admin :.966# Mesurez aux tarifs contractuels au lieu du prix catalogue USD. Nécessite admin:.
967# Avec managed:, les mêmes tarifs vont également aux clients connectés.
878# Les tarifs ci-dessous sont des espaces réservés, pas des prix de contrat réels.968# Les tarifs ci-dessous sont des espaces réservés, pas des prix de contrat réels.
879# pricing:969# pricing:
880# multiplier: 0.85970# multiplier: 0.85
929 - match: { groups: [contractors] }1019 - match: { groups: [contractors] }
930 cli:1020 cli:
931 availableModels: [claude-haiku-4-5]1021 availableModels: [claude-haiku-4-5]
932 # Contraindre l'option du sélecteur par défaut à availableModels au lieu1022 # Limitez l'option du sélecteur par défaut à availableModels au lieu de
933 # de la valeur par défaut du niveau, donc les entrepreneurs ne reçoivent pas un 400 sur la valeur par défaut.1023 # la valeur par défaut du niveau, afin que les entrepreneurs n'obtiennent pas une erreur 400 sur la valeur par défaut.
934 enforceAvailableModels: true1024 enforceAvailableModels: true
935 # allow approuve automatiquement ces outils ; il ne bloque pas le reste.1025 # allow approuve automatiquement ces outils ; il ne bloque pas le reste.
936 # Ajoutez des règles de refus pour restreindre les outils.1026 # Ajoutez des règles de refus pour restreindre les outils.
968 1058
969`parentSettingsBehavior: "merge"` maintient le fonctionnement de la livraison de la liste d'autorisation de sortie de Claude Desktop vers ses sessions Claude Code intégrées ; [Deliver policy to Claude Desktop sessions](/docs/fr/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions) explique le mécanisme et où l'opt-in doit se situer.1059`parentSettingsBehavior: "merge"` maintient le fonctionnement de la livraison de la liste d'autorisation de sortie de Claude Desktop vers ses sessions Claude Code intégrées ; [Deliver policy to Claude Desktop sessions](/docs/fr/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions) explique le mécanisme et où l'opt-in doit se situer.
970 1060
971Déployez le fichier `managed-settings.json` sur chaque appareil, généralement via votre plateforme MDM. Le chemin du fichier diffère selon la plateforme :1061Déployez le fichier `managed-settings.json` sur chaque appareil, généralement via votre plateforme MDM. Le chemin du fichier diffère selon la plateforme. Voir [où chaque mécanisme stocke la stratégie](/docs/fr/managed-settings#where-each-mechanism-stores-the-policy).
972
973| Plateforme | Chemin |
974| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
975| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json`, ou le domaine des préférences gérées `com.anthropic.claudecode` |
976| Linux et WSL | `/etc/claude-code/managed-settings.json` |
977| Windows | `C:\Program Files\ClaudeCode\managed-settings.json`, ou Group Policy via le registre HKLM |
978 1062
979Par défaut, une stratégie de registre sur Windows ou un plist de préférences gérées sur macOS remplace le fichier `managed-settings.json` plutôt que de le fusionner avec lui, à l'exception des [clés d'exception et des vérifications entre sources ci-dessus](#precedence-with-other-managed-sources). Les trois clés de cet extrait suivent la règle de source de priorité la plus élevée, donc les flottes qui livrent la stratégie via Group Policy ou les profils de configuration doivent placer les trois dans ce mécanisme à la place.1063Par défaut, une stratégie de registre sur Windows ou un plist de préférences gérées sur macOS remplace le fichier `managed-settings.json` plutôt que de le fusionner avec lui, à l'exception des [clés d'exception et des vérifications entre sources ci-dessus](#precedence-with-other-managed-sources). Les trois clés de cet extrait suivent la règle de source de priorité la plus élevée, donc les flottes qui livrent la stratégie via Group Policy ou les profils de configuration doivent placer les trois dans ce mécanisme à la place.
980 1064
