Implementación y operaciones de la puerta de enlace de aplicaciones Claude

Esta página cubre el lado operativo de ejecutar la puerta de enlace de aplicaciones Claude: registrar un cliente OAuth en su proveedor de identidad (IdP), implementar la puerta de enlace como un contenedor y ejecutarla día a día. Para cada opción en el archivo gateway.yaml que la puerta de enlace lee al iniciar, consulte la referencia de configuración. Una implementación de producción sigue cuatro pasos en orden, y las secciones a continuación coinciden con ellos. Los dos primeros son donde usted toma decisiones; los dos segundos son material de referencia para consultar una vez que esté en funcionamiento.

1. Configurar su proveedor de identidad: registre el cliente OAuth y verifique las notas específicas de cada IdP para Okta, Entra y Google
2. Implementar la puerta de enlace: construya una imagen de contenedor fijada y ejecútela en Kubernetes, Cloud Run o su propia plataforma. Esta sección también cubre decisiones sobre costo, omisión, múltiples puertas de enlace y sin servidor
3. Configurar operaciones: registros, sondeos de salud, comportamiento de interrupciones, rotación de secretos y actualizaciones. Referencia para cuando esté conectando monitoreo y runbooks
4. Revisar la postura de seguridad: qué datos fluyen hacia dónde, el modelo de amenaza y respuestas de cumplimiento. Referencia para una revisión de seguridad

Si un inicio de sesión o arranque falla en el camino, vaya directamente a Solución de problemas, que está indexada por el error que ve.

​

Configuración del proveedor de identidad

Registre una aplicación web confidencial de OAuth/OpenID Connect (OIDC) con un único URI de redirección, https://<gateway>/oauth/callback, y asígnela a los usuarios o grupos que deben tener acceso a la puerta de enlace. Cualquier IdP compatible con OIDC funciona: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate y otros. El IdP debe cumplir tres requisitos:

• Sirve /.well-known/openid-configuration, sobre HTTPS en producción; la puerta de enlace acepta un emisor http://, y un emisor de loopback además requiere CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
• Admite el flujo de código de autorización. PKCE (Proof Key for Code Exchange) está activado de forma predeterminada; desactívelo con oidc.use_pkce: false para IdPs que no lo admitan
• Devuelve email y opcionalmente groups en el id_token, o los sirve desde el punto final de userinfo con oidc.userinfo_fallback: true

Para PKI privada, establezca oidc.ca_cert_pem. Algunos proveedores manejan las reclamaciones de correo electrónico y grupo de manera diferente:

• Okta: el servidor de autorización de la organización en https://example.okta.com devuelve un id_token delgado que omite email y groups, así que establezca oidc.userinfo_fallback: true siempre que lo use como issuer. Un servidor de autorización personalizado como https://example.okta.com/oauth2/default que incluye email y opcionalmente groups en el id_token los emite directamente y no necesita fallback. Okta emite groups solo cuando se solicita el alcance groups en oidc.scopes y el filtro de reclamación de grupos de la aplicación lo permite; userinfo_fallback no puede llenar una reclamación que el IdP no fue solicitado.
• Microsoft Entra ID: issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra emite IDs de objeto de grupo en lugar de nombres, así que use los GUIDs en managed.policies.match.groups, o use App Roles para nombres legibles por humanos. Si su inquilino emite roles bajo roles en lugar de groups, establezca oidc.groups_claim: roles.
• Google Workspace: issuer = https://accounts.google.com. El id_token de Google no lleva grupos. Para usar allowed_groups basado en grupos o managed.policies con Google como IdP, configure oidc.google_groups, que busca los grupos de cada usuario a través de la API de directorio del SDK de administración usando una cuenta de servicio con delegación en todo el dominio. Sin él, use oidc.allowed_email_domains para control de membresía y managed.policies.match.email_domain para asignación de políticas. Google también ignora el alcance estándar offline_access. Para tokens de actualización, establezca oidc.scopes: [openid, profile, email] y oidc.extra_auth_params: { access_type: offline, prompt: consent }.

Para obtener soporte con un proveedor de identidad no cubierto anteriormente, consulte Solución de problemas.

​

Implementación

La puerta de enlace es un único binario de Linux. Se escala horizontalmente porque las réplicas son sin estado y Postgres es la capa de coordinación compartida. Ejecútela como ejecuta servicios sin estado en su entorno. El resto de esta sección establece lo que la imagen necesita, con notas breves para Kubernetes y Cloud Run. La puerta de enlace está diseñada para ejecutarse dentro de su red, porque contiene su credencial ascendente y actúa como el único punto de salida para la inferencia. Puede ejecutarse en cualquier lugar donde sus desarrolladores y su IdP puedan alcanzar sobre HTTPS; trátela como cualquier otro servicio que contiene una credencial de producción. Algunas decisiones dan forma a la implementación más allá de dónde se ejecuta:

• Costo: no hay licencia separada ni tarifa por asiento para la puerta de enlace; es parte del binario claude. Paga por inferencia a través de su compromiso existente en la nube o con Anthropic, más el cálculo para el contenedor y su recopilador de telemetría.
• Derivación: la puerta de enlace no impone que la única ruta a un modelo pase por ella. Un desarrollador con su propia credencial aún puede llamar al proveedor directamente, así que cerrar ese camino es una decisión de política de red, por ejemplo bloqueando la salida a api.anthropic.com excepto desde la puerta de enlace. Bloquear esa salida también rompe la verificación de seguridad de dominio de WebFetch, que llama a api.anthropic.com desde la máquina de cada desarrollador; establezca skipWebFetchPreflight: true en la política administrada para deshabilitarlo.
• Múltiples puertas de enlace: cada puerta de enlace es una implementación separada con su propia configuración. El CLI almacena su huella digital de confianza y credenciales por nombre de host de puerta de enlace, así que diferentes equipos pueden conectarse a diferentes puertas de enlace sin conflicto. Para servir múltiples emisores OIDC, ejecute instancias separadas.
• Sin servidor: Cloud Run funciona; establezca min-instances: 1 para evitar descubrimiento OIDC frío. Lambda y Cloud Functions no, porque la puerta de enlace es un servidor HTTP de larga duración.

Cada topología de producción aquí coloca un proxy L7, como un Ingress, el front-end de Cloud Run o un ALB, frente a réplicas HTTP simples. Establezca listen.trusted_proxies en los rangos de origen del proxy para que la puerta de enlace lea las IPs del cliente desde X-Forwarded-For. La puerta de enlace honra el encabezado solo cuando el par TCP es confiable; el ejemplo trabajado de Google Cloud tiene valores concretos por topología. Sin proxies confiables, cada solicitud parece provenir de la IP del proxy, lo que colapsa los límites de velocidad por IP en un cubo compartido y registra la IP del proxy en eventos de auditoría.

​

Imagen de contenedor

Construya su propia imagen alrededor del binario nativo claude de la versión estándar de Claude Code:

1. Descargue la compilación de Linux para la arquitectura de su imagen desde una versión fija; consulte Instalar una versión específica para la URL de descarga.
2. Verifíquelo contra el manifest.json firmado con GPG de la versión como se describe en Integridad binaria y firma de código.
3. Cópielo en el contexto de compilación.

Refleje la versión en su registro interno si sus compilaciones no pueden alcanzar el host de versión, y fije la versión que ejecuta su flota. Más allá del binario, la imagen necesita:

• Una imagen basada en glibc: las únicas dependencias dinámicas de la compilación de glibc son las bibliotecas de glibc. Las imágenes basadas en Musl necesitan la compilación linux-x64-musl o linux-arm64-musl más paquetes adicionales; consulte Configuración de Alpine Linux.
• Un directorio de estado escribible: la puerta de enlace se ejecuta como cualquier usuario, pero las imágenes mínimas no tienen inicio escribible. Establezca CLAUDE_CONFIG_DIR en una ruta escribible como /tmp/.claude.
• El comando del contenedor: claude gateway --config /etc/claude/gateway.yaml, con el archivo de configuración montado de solo lectura y secretos suministrados como variables de entorno; la puerta de enlace escucha en listen.port, predeterminado 8080.

​

Kubernetes

Ejecute la puerta de enlace como una Deployment, como cualquier servicio sin estado:

• Monte la configuración desde un ConfigMap y secretos desde un Secret; haga referencia a secretos en el YAML a través de ${file:/path/to/secret} o como variables de entorno
• Termine TLS en el Ingress y establezca listen.public_url en el nombre de host de Ingress
• Apunte la sonda de preparación a GET /readyz y la sonda de vivacidad a GET /healthz

​

Cloud Run

Configure el servicio de la siguiente manera:

• Deje listen.port en su predeterminado de 8080, que coincide con el PORT predeterminado de Cloud Run, o establezca port: ${PORT}
• Establezca public_url en el origen externamente alcanzable. Para producción esto es normalmente el nombre de host de un equilibrador de carga interno, porque /login rechaza direcciones públicas y la URL *.run.app se resuelve a una, así que la URL de Cloud Run sola funciona solo para una prueba de humo curl o navegador. La excepción es una red donde *.run.app se resuelve privadamente a través de Private Service Connect y una zona privada de Cloud DNS; en esa topología la URL de Cloud Run es un public_url válido. El ejemplo trabajado de Google Cloud cubre ambos.
• Monte la configuración como un volumen secreto
• Establezca min-instances: 1 para evitar un descubrimiento OIDC frío en la primera solicitud

​

Enviar la URL de la puerta de enlace a máquinas de desarrolladores

Una vez que la puerta de enlace está sirviendo, envíe forceLoginMethod y forceLoginGatewayUrl a la máquina de cada desarrollador a través de configuraciones administradas, a través de MDM o escribiendo directamente el managed-settings.json específico del sistema operativo. Sin esto, /login muestra el selector de cuenta estándar sin opción de puerta de enlace. Consulte Configuraciones administradas del lado del cliente para las rutas de archivo.

​

Operaciones

Una vez que la puerta de enlace está sirviendo tráfico, la operación día a día es leer sus registros, sondear su salud y rotar sus secretos en su horario. Las subsecciones cubren cada una, más lo que Postgres contiene y cómo se comportan las actualizaciones y reversiones.

​

Registros

La puerta de enlace escribe dos flujos a stderr, ambos amigables con JSON:

• Eventos de auditoría: JSON de una sola línea por evento relevante para la seguridad. Canalice stderr a su agregador de registros. Los eventos emitidos incluyen config.load, session.mint, session.refresh, device.authorize, device.verify, auth.denied, access.denied, inference, managed.serve, spend.blocked y admin.denied. Los campos varían según el evento:
  • Los eventos de acuñación y actualización exitosos llevan sub, email, client_ip y el resultado
  • Los eventos de denegación llevan la razón, ruta e IP del cliente, ya que no existe identidad en la denegación
  • inference registra qué ascendente sirvió la solicitud y el estado de respuesta
  • admin.denied registra un intento de autenticación de API de administrador rechazado con la razón (invalid_key o no_credentials), IP del cliente, método y ruta, sin el material de clave presentado
• Registros operacionales: líneas legibles por humanos con prefijo [gateway] para arranque, advertencias y errores ascendentes. La variable de entorno CLAUDE_GATEWAY_LOG_LEVEL controla la verbosidad y acepta info, warn o error, con info como predeterminado. No afecta los eventos de auditoría, que siempre se emiten.

​

Salud

La puerta de enlace sirve GET /healthz como una sonda de vivacidad y GET /readyz como una sonda de preparación; /readyz verifica que el almacén sea alcanzable. Ambas están exentas de access_control.allow_cidrs, así que los sondeos siguen funcionando en un oyente bloqueado. El documento de descubrimiento de OAuth en /.well-known/oauth-authorization-server también devuelve 200 solo después de que se cargue la configuración, descubrimiento OIDC, construcción de cliente ascendente y migración de Postgres tengan éxito, así que funciona como una verificación de arranque de extremo a extremo. Una puerta de enlace en ejecución también sirve una descripción de las rutas y formas de solicitud que acepta en <public_url>/protocol, coincidida con la versión que está ejecutando. El contenido no es estable entre versiones.

​

Comportamiento de interrupciones

Si Postgres se cae, la puerta de enlace en sí sigue sirviendo desarrolladores con sesión iniciada y los nuevos inicios de sesión fallan. Si los desarrolladores realmente siguen trabajando depende de cómo su orquestador maneja la preparación:

• Sesiones existentes: los tokens portadores se validan localmente con el secreto JWT, las actualizaciones de sesión no tocan el almacén, y el proceso de puerta de enlace aún puede servir inferencia
• Nuevos inicios de sesión: fallan hasta que Postgres se recupere, porque el flujo de dispositivo y sus contadores de límite de velocidad viven en Postgres
• Cumplimiento de límite de gasto: falla abierto de forma predeterminada durante la interrupción, así que la inferencia aún fluye; cámbielo a falla cerrada si preferiría bloquear que ejecutar sin medidor
• Preparación: /readyz reporta no listo durante la interrupción, así que los orquestadores que cierren tráfico en preparación eliminan cada réplica de rotación a la vez. En esa topología todo el tráfico, incluida la inferencia que la puerta de enlace podría servir, falla en el equilibrador de carga hasta que Postgres se recupere. La sonda de vivacidad en /healthz sigue pasando, así que las réplicas no se reinician. Apunte la sonda de preparación a /healthz en su lugar si preferiría que los desarrolladores con sesión iniciada sigan trabajando a través de una interrupción de almacén; el costo es que los nuevos inicios de sesión fallan contra una réplica que aún reporta lista.

Si su IdP se cae, las sesiones existentes funcionan hasta ttl_hours, y los nuevos inicios de sesión y actualizaciones fallan. Establezca un ttl_hours más largo si su IdP tiene ventanas de mantenimiento frecuentes.

​

Rotación de secreto JWT

Rote el secreto de firma en tres pasos para que las sesiones existentes permanezcan válidas:

1. Genere un nuevo secreto. Antepóngalo a la matriz session.jwt_secret.
2. Despliegue la implementación. Los nuevos tokens firman con el nuevo secreto; los tokens antiguos aún se verifican.
3. Después de ttl_hours más un margen, elimine el secreto antiguo y despliegue nuevamente.

La rotación también es la única forma de forzar sesiones antes de que expiren: los tokens portadores se validan localmente contra el secreto JWT, así que no hay revocación por sesión. Reemplazar el secreto directamente, sin mantener el antiguo en la matriz, invalida cada sesión pendiente a la vez. Para desaprovisionamiento individual, desaprovision el usuario en su IdP; su sesión termina dentro de ttl_hours.

​

Postgres

La puerta de enlace contiene cinco tablas, todas creadas por sus migraciones de tiempo de arranque: Un bucle de 30 segundos expira filas kv pasadas su TTL, y un barrido cada hora impone las ventanas de retención en las tablas de gasto, así que nada crece sin límite. Sin límites de gasto configurados, solo se escribe kv. Si su política de seguridad prohíbe DDL del rol de aplicación, pre-cree estas tablas y _migrations con un rol de administrador y otorgue al rol de aplicación SELECT, INSERT, UPDATE, DELETE en cada una. Con límites de gasto en uso, una base de datos perdida significa pérdida de seguimiento de gasto y límites, no solo re-inicios de sesión de desarrolladores, así que ejecute copias de seguridad regulares. Para borrar un desarrollador que se fue inmediatamente en lugar de esperar en retención, ejecute DELETE FROM principal_emails WHERE principal = '<sub>' directamente; eso elimina la única tabla que contiene su correo electrónico, nombre y grupos. Las filas spend y admin_audit hacen referencia solo al sub OIDC seudónimo.

​

Actualizaciones

Las réplicas son sin estado, así que un reinicio rodante es seguro en cualquier momento. La puerta de enlace ejecuta migraciones de esquema al arrancar, lo que significa que implementar el nuevo binario auto-migra la base de datos. Si el rol de base de datos no puede ejecutar DDL, pre-cree el esquema, incluida la tabla _migrations sembrada a la versión actual; de lo contrario el arranque falla intentando CREATE TABLE. Las migraciones son solo anexo, así que revertir a un binario anterior que conoce menos migraciones es seguro; ignora las filas adicionales. La reversión también re-valida el YAML contra el esquema del binario más antiguo, así que una configuración que adoptó una clave introducida por la versión más nueva falla al arrancar en la más antigua. Elimine la nueva clave antes de revertir. Porque fija la versión de la puerta de enlace en su propia imagen, las correcciones en nuevas versiones de Claude Code, incluidas las correcciones de seguridad, llegan a su implementación solo cuando actualiza el pin y redeploy. Incluya la puerta de enlace en el mismo ciclo de parches que usa para otros servicios que contienen credenciales de producción.

​

Seguridad

Esta sección responde las preguntas que una revisión de seguridad hace: qué datos fluyen a través de la puerta de enlace y hacia dónde van, qué ataques defiende el diseño, y qué respuestas pertenecen en un cuestionario de cumplimiento.

​

Flujo de datos

​

Resumen del modelo de amenaza

La puerta de enlace se sienta dentro de su perímetro de red, pero las máquinas portátiles de desarrolladores individuales no se tratan como confiables. El diseño cuenta para esto de tres maneras:

• Los desarrolladores sostienen JWTs de corta duración en lugar de claves ascendentes sin procesar. La pierna CLI-a-puerta de enlace usa la concesión de dispositivo RFC 8628, y el intercambio de código de autorización de la puerta de enlace con el IdP ejecuta PKCE en la configuración predeterminada, así que un código de autorización de IdP interceptado es inútil.
• La página de verificación de dispositivo impone POST del mismo origen y un límite de velocidad por IP por RFC 8628 §5.1. Consulte Resistencia de fuerza bruta de código de usuario.
• Las solicitudes salientes pasan por una protección de falsificación de solicitud del lado del servidor (SSRF) que resuelve DNS, bloquea direcciones de enlace local y metadatos en la nube más loopback de forma predeterminada, y fija la conexión a la IP resuelta, así que URLs influenciadas por el operador como el IdP y destinos OTLP no pueden ser redirigidas a puntos finales de metadatos en la nube. Los rangos privados RFC 1918 se permiten deliberadamente, porque los IdPs y recopiladores OTLP comúnmente viven en IPs privadas. Para desarrollo local contra un IdP de loopback o recopilador, establezca CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 en el entorno de la puerta de enlace; déjelo sin establecer en producción.

Si agrega sus propios controles de salida, la puerta de enlace debe alcanzar el servidor de metadatos siempre que use credenciales de metadatos de instancia como identidad de carga de trabajo. Dos amenazas están fuera del alcance porque son su infraestructura para asegurar:

• Un host de puerta de enlace comprometido: el host tanto contiene la credencial ascendente como distribuye configuraciones administradas a cada desarrollador conectado, así que el control sobre la configuración de la puerta de enlace es comparable al control sobre su MDM. El diálogo de aprobación única del CLI para configuraciones capaces de shell limita cambios silenciosos pero no reemplaza la seguridad del host.
• Un proveedor OIDC malicioso: el proveedor firma los id_tokens que la puerta de enlace confía, así que puede afirmar cualquier identidad. Verificar y asegurar su IdP es su responsabilidad.

​

Resistencia de fuerza bruta de código de usuario

El user_code que un desarrollador escribe en la página de verificación /device son 8 caracteres extraídos de un alfabeto de 20 caracteres, que produce 20⁸ o aproximadamente 2.56×10¹⁰ combinaciones, y expira después de 10 minutos. La puerta de enlace aplica límites de velocidad por IP en los puntos finales de concesión de dispositivo, configurables a través de rate_limits. Aumente los límites si muchos desarrolladores inician sesión desde una única dirección NAT corporativa compartida. Los límites se aplican solo al flujo de inicio de sesión, no a la inferencia.

​

Postura de cumplimiento

• Residencia de datos: el plano de datos propio de la puerta de enlace no envía nada a Anthropic a menos que la API de Anthropic sea un ascendente configurado; cuando lo es, su acuerdo de manejo de datos existente se aplica a la ruta de inferencia. Telemetría, auditoría, identidad y configuraciones van solo a los destinos que configura.
• Tráfico de proceso de host: el proceso de host es el CLI de Claude Code, que puede enviar análisis de inicio y verificaciones de actualización a Anthropic. Para implementaciones de salida estricta, establezca CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 en el entorno del contenedor de la puerta de enlace.
• Análisis del cliente: el CLI deshabilita su propio análisis de uso mientras está conectado a una puerta de enlace, y el informe de errores está desactivado de forma predeterminada en superficies de API de terceros.
• Máquinas cliente: los CLIs de desarrolladores aún envían verificaciones de nombre de host de WebFetch y verificaciones de versión a Anthropic a menos que CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 y skipWebFetchPreflight: true estén establecidos. Consulte uso de datos.
• Calificaciones de encuesta: la credencial de puerta de enlace deshabilita el sumidero de calificación vinculado a Anthropic, así que las calificaciones no se envían a Anthropic.
• Compartir transcripción: elegir Sí en el indicador de compartir transcripción de una encuesta escribe un archivo local bajo ~/.claude/feedback-bundles/ en lugar de cargar a Anthropic.
• Actualizaciones del cliente: las verificaciones de actualización son separadas del tráfico de puerta de enlace. Fije versiones a través de su propia distribución y establezca DISABLE_UPDATES si las máquinas portátiles no deben obtener versiones. DISABLE_AUTOUPDATER detiene solo actualizaciones de fondo mientras claude update aún funciona.
• TLS: sirva public_url sobre HTTPS en producción, ya sea desde el oyente propio de la puerta de enlace a través de listen.tls o desde un ingress que termina TLS frente a réplicas HTTP simples con listen.public_url establecido. La puerta de enlace no rechaza HTTP simple. El IdP debe servir HTTPS en producción, y Postgres admite ?sslmode=require. Establezca Strict-Transport-Security en su ingress.
• Divulgación de vulnerabilidad: siga Reportar problemas de seguridad

​

Solución de problemas

Para preguntas y comentarios, use soporte de Claude Code, o abra un problema en el repositorio de GitHub de Claude Code. Al reportar un problema, incluya:

• Problema de puerta de enlace: el stderr de la puerta de enlace para la ventana relevante, su gateway.yaml con secretos redactados, la versión de la puerta de enlace, mostrada en la página de inicio en / y en el encabezado de respuesta x-cc-gateway-version en /managed/settings, y qué cambió recientemente
• Problema de inicio de sesión: el desarrollador ejecuta claude --debug-file ./claude-debug.txt, reproduce, y envía ese archivo más el registro de auditoría de la puerta de enlace para la misma ventana
• Problema de inferencia: el modelo solicitado, los ascendentes configurados, y el registro de auditoría de la puerta de enlace para la solicitud, que registra qué ascendente la sirvió y el estado de respuesta

​

Relacionado

• Descripción general de la puerta de enlace de aplicaciones Claude: inicio rápido y conexión de desarrolladores
• Referencia de configuración: cada opción de gateway.yaml