79| Campo | Requerido | Descripción |79| Campo | Requerido | Descripción |
80| - | - | - |80| - | - | - |
81| `issuer` | Sí | Base de descubrimiento OIDC. Debe servir el descubrimiento en `/.well-known/openid-configuration`. Use HTTPS en producción; la puerta de enlace acepta un emisor `http://`. Un emisor loopback como `http://localhost:8081` es rechazado por la [protección SSRF](/docs/es/claude-apps-gateway-deploy#threat-model-summary) a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esté establecido en el entorno de la puerta de enlace. |81| `issuer` | Sí | Base de descubrimiento OIDC. Debe servir el descubrimiento en `/.well-known/openid-configuration`. Use HTTPS en producción; la puerta de enlace acepta un emisor `http://`. Un emisor loopback como `http://localhost:8081` es rechazado por la [protección SSRF](/docs/es/claude-apps-gateway-deploy#threat-model-summary) a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esté establecido en el entorno de la puerta de enlace. |
82| `client_id` / `client_secret` | Sí | De su registro de cliente OAuth |82| `client_id` | Sí | De tu registro de cliente OAuth |
83| `client_secret` | A menos que `token_endpoint_auth_method` sea `private_key_jwt` | De tu registro de cliente OAuth. Omítelo cuando uses [autenticación de cliente con certificado](#certificate-client-authentication). |
83| `allowed_email_domains` | No | Rechace id\_tokens cuya reclamación `email` no esté en uno de estos dominios, sin distinción de mayúsculas y minúsculas. Defensa en profundidad contra configuración errónea del IdP multiinquilino. Independientemente de esta configuración, un id\_token cuya reclamación `email_verified` es explícitamente `false` siempre se rechaza. |84| `allowed_email_domains` | No | Rechace id\_tokens cuya reclamación `email` no esté en uno de estos dominios, sin distinción de mayúsculas y minúsculas. Defensa en profundidad contra configuración errónea del IdP multiinquilino. Independientemente de esta configuración, un id\_token cuya reclamación `email_verified` es explícitamente `false` siempre se rechaza. |
84| `allowed_groups` | No | Restrinja el inicio de sesión a miembros de estos grupos del IdP, comparados contra `groups_claim`. Un usuario en un dominio de correo electrónico permitido pero en ninguno de estos grupos es rechazado. Requiere que el IdP emita la reclamación de grupos. La coincidencia es una comparación de cadena exacta y sensible a mayúsculas y minúsculas contra los valores en esa reclamación, y la puerta de enlace no expande grupos anidados: para admitir miembros de un subgrupo, enumere el subgrupo aquí o configure el IdP para emitir membresía aplanada. |85| `allowed_groups` | No | Restrinja el inicio de sesión a miembros de estos grupos del IdP, comparados contra `groups_claim`. Un usuario en un dominio de correo electrónico permitido pero en ninguno de estos grupos es rechazado. Requiere que el IdP emita la reclamación de grupos. La coincidencia es una comparación de cadena exacta y sensible a mayúsculas y minúsculas contra los valores en esa reclamación, y la puerta de enlace no expande grupos anidados: para admitir miembros de un subgrupo, enumere el subgrupo aquí o configure el IdP para emitir membresía aplanada. |
85| `groups_claim` | No | Qué reclamación id\_token lleva la membresía del grupo. Por defecto `groups`. Microsoft Entra emite roles de aplicación bajo `roles`. Acepta una clave plana o un Puntero JSON RFC 6901 como `/resource_access/gateway/roles` para reclamaciones anidadas. |86| `groups_claim` | No | Qué reclamación id\_token lleva la membresía del grupo. Por defecto `groups`. Microsoft Entra emite roles de aplicación bajo `roles`. Acepta una clave plana o un Puntero JSON RFC 6901 como `/resource_access/gateway/roles` para reclamaciones anidadas. |
91| `userinfo_fallback` | No | Cuando el id\_token omite correo electrónico o grupos, búsquelos en `/userinfo`. Necesario para tokens de acceso ligeros de Keycloak, el servidor org de Okta, y tokens mínimos de ADFS. El id\_token sigue siendo autoritario; userinfo solo llena vacíos. Por defecto `false`. |92| `userinfo_fallback` | No | Cuando el id\_token omite correo electrónico o grupos, búsquelos en `/userinfo`. Necesario para tokens de acceso ligeros de Keycloak, el servidor org de Okta, y tokens mínimos de ADFS. El id\_token sigue siendo autoritario; userinfo solo llena vacíos. Por defecto `false`. |
92| `use_pkce` | No | Envíe un desafío PKCE (S256) en la solicitud de autorización. Por defecto `true`. Establezca `false` solo si su IdP rechaza PKCE para este cliente confidencial. |93| `use_pkce` | No | Envíe un desafío PKCE (S256) en la solicitud de autorización. Por defecto `true`. Establezca `false` solo si su IdP rechaza PKCE para este cliente confidencial. |
93| `clock_skew_seconds` | No | Tolere la desviación del reloj al validar reclamaciones de tiempo id\_token. Por defecto `0`, que es estricto. Aumente si ve errores "token expirado / aún no válido" justo después del inicio de sesión debido a desviación del reloj del host/IdP. |94| `clock_skew_seconds` | No | Tolere la desviación del reloj al validar reclamaciones de tiempo id\_token. Por defecto `0`, que es estricto. Aumente si ve errores "token expirado / aún no válido" justo después del inicio de sesión debido a desviación del reloj del host/IdP. |
94| `token_endpoint_auth_method` | No | Anule el método de autenticación del punto final del token. Acepta `client_secret_basic` o `client_secret_post`. Negociado automáticamente por defecto. |95| `token_endpoint_auth_method` | No | Cómo se autentica el gateway ante el endpoint de token del IdP: `client_secret_basic`, `client_secret_post` o `private_key_jwt` para la [autenticación de cliente con certificado](#certificate-client-authentication). Por defecto, el gateway elige uno de los dos métodos `client_secret` según lo que anuncie el IdP. |
96| `client_assertion` | Con `private_key_jwt` | Un bloque con `private_key_pem` y `certificate_pem`: la clave privada y el certificado para la [autenticación de cliente con certificado](#certificate-client-authentication). Requiere v2.1.284 o posterior. |
95| `id_token_signed_response_alg` | No | Algoritmo de firma id\_token esperado. Por defecto `RS256`. Establezca para IdPs que firman con ES256, PS256, o EdDSA. |97| `id_token_signed_response_alg` | No | Algoritmo de firma id\_token esperado. Por defecto `RS256`. Establezca para IdPs que firman con ES256, PS256, o EdDSA. |
96| `additional_authorized_parties` | No | Valores `azp` adicionales para aceptar más allá de `client_id`, para flujos de intermediario de Keycloak e intercambio de tokens |98| `additional_authorized_parties` | No | Valores `azp` adicionales para aceptar más allá de `client_id`, para flujos de intermediario de Keycloak e intercambio de tokens |
97| `discovery_url` | No | Busque el documento de descubrimiento desde esta URL en lugar de derivarlo de `issuer`, para IdPs detrás de un proxy que reescribe el host del emisor. La ruta debe contener `/.well-known/`. |99| `discovery_url` | No | Busque el documento de descubrimiento desde esta URL en lugar de derivarlo de `issuer`, para IdPs detrás de un proxy que reescribe el host del emisor. La ruta debe contener `/.well-known/`. |
99| `form_action_origins` | No | Orígenes adicionales para la directiva `Content-Security-Policy: form-action` de la página `/device`. La puerta de enlace ya permite `'self'` y el origen `authorization_endpoint` descubierto, pero Chrome aplica `form-action` contra toda la cadena de redirección. Si su IdP redirige a través de un segundo host, como Azure AD federado a ADFS, Okta de concentrador y radio, o un interceptor SSO corporativo, enumere cada origen por el que la solicitud de autorización puede redirigir. |101| `form_action_origins` | No | Orígenes adicionales para la directiva `Content-Security-Policy: form-action` de la página `/device`. La puerta de enlace ya permite `'self'` y el origen `authorization_endpoint` descubierto, pero Chrome aplica `form-action` contra toda la cadena de redirección. Si su IdP redirige a través de un segundo host, como Azure AD federado a ADFS, Okta de concentrador y radio, o un interceptor SSO corporativo, enumere cada origen por el que la solicitud de autorización puede redirigir. |
100| `ca_cert_pem` | No | El certificado CA codificado en PEM en sí, no una ruta a un archivo. Reemplaza el almacén de confianza del sistema solo para solicitudes del IdP. Para cargar un archivo montado, escriba `${file:/etc/gateway/idp-ca.pem}`. Úselo para Keycloak o Dex detrás de PKI corporativa. |102| `ca_cert_pem` | No | El certificado CA codificado en PEM en sí, no una ruta a un archivo. Reemplaza el almacén de confianza del sistema solo para solicitudes del IdP. Para cargar un archivo montado, escriba `${file:/etc/gateway/idp-ca.pem}`. Úselo para Keycloak o Dex detrás de PKI corporativa. |
101 103
104<h4 id="certificate-client-authentication">
105 Autenticación de cliente con certificado
106</h4>
107
108Si tu proveedor de identidad autentica a los clientes OAuth con un certificado en lugar de un secreto de cliente, como hace Microsoft Entra con las credenciales de certificado, establece `token_endpoint_auth_method: private_key_jwt`. Requiere Claude Code v2.1.284 o posterior en el servidor del gateway.
109
110Con esta configuración, el gateway no envía ningún secreto. Se autentica ante el endpoint de token del IdP con un JWT de corta duración firmado con la clave privada del certificado cuando un desarrollador inicia sesión y cada vez que el gateway actualiza su sesión. El JWT se firma con RS256 e identifica el certificado mediante los encabezados de huella digital `x5t` y `x5t#S256` en lugar de un `kid`. Tu IdP debe poder encontrar el certificado registrado por su huella digital.
111
112<Steps>
113 <Step title="Crea la clave y el certificado">
114 Crea una clave privada RSA sin cifrar de al menos 2048 bits, en formato PEM PKCS#8 o PKCS#1, y un certificado para ella. El gateway se niega a iniciar con cualquier clave que no cumpla estas condiciones. Este comando `openssl` crea una clave así con un certificado autofirmado válido durante un año:
115
116 ```bash theme={null}
117 openssl req -x509 -newkey rsa:2048 -nodes -keyout idp-client.key -out idp-client.crt -days 365 -subj "/CN=claude-gateway"
118 ```
119
120 Escribe `idp-client.key` e `idp-client.crt` en el directorio actual. Copia o monta ambos archivos donde el gateway pueda leerlos. El ejemplo del paso 3 usa `/etc/gateway/`.
121 </Step>
122
123 <Step title="Sube el certificado al IdP">
124 Sube el certificado, no la clave privada, al registro de aplicación del gateway en el IdP.
125 </Step>
126
127 <Step title="Agrega la clave y el certificado a gateway.yaml">
128 Proporciona al gateway la clave privada y el certificado en un bloque `client_assertion`. Omite `client_secret`, porque el gateway se niega a iniciar cuando se establece junto con `private_key_jwt`. Este bloque `oidc` autentica el gateway ante un inquilino de Microsoft Entra con un certificado:
129
130 ```yaml theme={null}
131 oidc:
132 issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
133 client_id: <application-id>
134 token_endpoint_auth_method: private_key_jwt
135 client_assertion:
136 private_key_pem: ${file:/etc/gateway/idp-client.key}
137 certificate_pem: ${file:/etc/gateway/idp-client.crt}
138 ```
139
140 Ambos valores son el contenido PEM, no rutas de archivo, así que carga los archivos montados con `${file:/path}` como hace el ejemplo. El gateway se niega a iniciar a menos que `certificate_pem` sea un único certificado PEM, sin el resto de su cadena, cuya clave pública coincida con `private_key_pem`.
141 </Step>
142
143 <Step title="Reinicia el gateway y revisa el registro de arranque">
144 Reinicia el gateway y busca esta línea en el registro de arranque:
145
146 ```text theme={null}
147 [gateway] 2026-10-01T23:07:40.512Z info oidc: client authentication private_key_jwt; certificate CN=claude-gateway, SHA-1 thumbprint DE92821854EE8BAA1D98C758FAA04AABE80B9F57, expires Oct 1 23:07:31 2027 GMT
148 ```
149
150 Compara la huella digital SHA-1 con la que muestra el IdP para el certificado que subiste. Si el certificado ha expirado o aún no es válido, el gateway igualmente inicia, pero registra una advertencia de que los inicios de sesión y las actualizaciones fallarán hasta que lo reemplaces. Para confirmar que el IdP acepta el certificado, pide a un desarrollador que inicie sesión a través del gateway.
151 </Step>
152</Steps>
153
154<h4 id="rotate-the-client-certificate">
155 Rotar el certificado de cliente
156</h4>
157
158El gateway lee la clave y el certificado una sola vez al arrancar, así que un archivo modificado solo surte efecto tras un reinicio. Rota en este orden para que ninguna solicitud de token presente un certificado que el IdP no tenga:
159
1601. Sube el nuevo certificado al IdP junto al antiguo.
1612. Reemplaza los archivos de clave y certificado que carga `gateway.yaml` y luego reinicia el gateway.
1623. Elimina el certificado antiguo del IdP.
163
102<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">
103 Solicitudes del IdP a través de un proxy directo165 Solicitudes del IdP a través de un proxy directo
104</h4>166</h4>
