Autenticación mediante proxy de confianza

Cuándo usarlo

• Ejecuta OpenClaw detrás de un proxy con reconocimiento de identidad (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + autenticación reenviada).
• Su proxy gestiona toda la autenticación y transmite la identidad del usuario mediante encabezados.
• Se encuentra en un entorno de Kubernetes o contenedores donde el proxy es la única ruta al Gateway.
• Recibe errores de WebSocket 1008 unauthorized porque los navegadores no pueden enviar tokens en las cargas útiles de WS.

Cuándo NO usarlo

• Su proxy no autentica a los usuarios (solo actúa como terminador TLS o balanceador de carga).
• Existe alguna ruta al Gateway que evita el proxy (brechas en el cortafuegos, acceso desde la red interna).
• No está seguro de que su proxy elimine o sobrescriba correctamente los encabezados reenviados.
• Solo necesita acceso personal para un único usuario (considere Tailscale Serve + local loopback en su lugar).

Cómo funciona

Configuración

{  gateway: {    // La autenticación mediante proxy de confianza espera de forma predeterminada que la IP de origen del proxy no sea de loopback    bind: "lan",     // CRÍTICO: Añada aquí únicamente las IP de su proxy    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // Encabezado que contiene la identidad del usuario autenticado (obligatorio)        userHeader: "x-forwarded-user",         // Opcional: encabezados que DEBEN estar presentes (verificación del proxy)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // Opcional: restringir a usuarios específicos (vacío = permitir a todos)        allowUsers: ["nick@example.com", "admin@company.org"],         // Opcional: permitir un proxy de loopback en el mismo host tras habilitarlo explícitamente        allowLoopback: false,      },    },  },}

Referencia de configuración

Comportamiento del emparejamiento de la interfaz de control

Cuando gateway.auth.mode = "trusted-proxy" está activo y la solicitud supera las comprobaciones del proxy de confianza, las sesiones WebSocket de la interfaz de control pueden conectarse sin una identidad de emparejamiento del dispositivo.

Implicaciones de los ámbitos:

• Las sesiones WebSocket de la interfaz de control sin dispositivo se conectan, pero de forma predeterminada no reciben ningún ámbito de operador. OpenClaw borra la lista de ámbitos solicitados y la establece en [] para que una sesión no vinculada a un dispositivo o token emparejado y aprobado no pueda autodeclarar permisos.
• Si los métodos fallan con missing scope tras establecer correctamente una conexión WebSocket, use HTTPS para que el navegador pueda generar la identidad del dispositivo y completar el emparejamiento. Consulte HTTP no seguro de la interfaz de control.
• Solo para emergencias: gateway.controlUi.dangerouslyDisableDeviceAuth=true conserva los ámbitos solicitados incluso sin identidad del dispositivo. Esto supone una grave reducción de la seguridad; reviértalo cuanto antes. Consulte HTTP no seguro de la interfaz de control.

Limitación de ámbitos mediante el proxy inverso: si su proxy envía x-openclaw-scopes en la solicitud de actualización a WebSocket de la interfaz de control, OpenClaw limita los ámbitos de la sesión a la intersección de los ámbitos solicitados y los declarados. Este encabezado no concede ámbitos; solo restringe los que puede tener la sesión.

Implicaciones:

• El emparejamiento deja de ser el control principal para acceder a la interfaz de control en este modo.
• La política de autenticación de su proxy inverso y allowUsers se convierten en el control de acceso efectivo.
• Mantenga la entrada al Gateway restringida únicamente a las IP de los proxies de confianza (gateway.trustedProxies + cortafuegos).

Los clientes WebSocket personalizados no son sesiones de la interfaz de control. gateway.controlUi.dangerouslyDisableDeviceAuth no concede ámbitos a clientes arbitrarios con client.mode: "backend" ni a clientes con formato de CLI. La automatización personalizada debe usar la identidad y el emparejamiento del dispositivo, la ruta auxiliar reservada del backend local directo client.id: "gateway-client" o el Plugin RPC HTTP de administración cuando resulte más adecuada una interfaz HTTP de solicitud y respuesta.

Encabezado de ámbitos del operador

La autenticación mediante proxy de confianza es un modo HTTP que incorpora identidad, por lo que los clientes pueden declarar opcionalmente ámbitos de operador mediante x-openclaw-scopes en las solicitudes a la API HTTP.

Nota: los ámbitos de WebSocket se determinan mediante el protocolo de enlace del Gateway y la vinculación de la identidad del dispositivo. En las solicitudes de actualización a WebSocket de la interfaz de control, x-openclaw-scopes solo limita los ámbitos negociados de la sesión; no los concede. Consulte Comportamiento del emparejamiento de la interfaz de control.

Ejemplos:

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

Comportamiento:

• Cuando el encabezado está presente, OpenClaw respeta el conjunto de ámbitos declarado.
• Cuando el encabezado está presente, pero vacío, la solicitud declara que no tiene ningún ámbito de operador.
• Cuando el encabezado está ausente, las API HTTP normales que incorporan identidad recurren al conjunto predeterminado estándar de ámbitos de operador (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Las rutas HTTP de Plugin con autenticación del Gateway tienen un valor predeterminado más restringido: cuando x-openclaw-scopes está ausente, su ámbito de ejecución se limita a operator.write.
• Las solicitudes HTTP originadas en navegadores deben seguir cumpliendo gateway.controlUi.allowedOrigins (o el modo alternativo deliberado basado en el encabezado Host), incluso después de superar la autenticación mediante proxy de confianza.

Regla práctica: envíe x-openclaw-scopes explícitamente cuando quiera que una solicitud mediante proxy de confianza tenga menos privilegios que los predeterminados o cuando una ruta de Plugin con autenticación del Gateway necesite algo más potente que el ámbito de escritura.

Terminación TLS y HSTS

Use un único punto de terminación TLS y aplique HSTS allí.

Strict-Transport-Security: max-age=31536000; includeSubDomains

{  gateway: {    tls: { enabled: true },    http: {      securityHeaders: {        strictTransportSecurity: "max-age=31536000; includeSubDomains",      },    },  },}

Guía de implementación

• Comience con una duración máxima corta (por ejemplo, max-age=300) mientras valida el tráfico.
• Auméntela a valores de larga duración (por ejemplo, max-age=31536000) solo cuando tenga un alto grado de confianza.
• Añada includeSubDomains únicamente si todos los subdominios están preparados para HTTPS.
• Use la precarga solo si cumple intencionadamente sus requisitos para todo el conjunto de dominios.
• El desarrollo local únicamente mediante loopback no se beneficia de HSTS.

Ejemplos de configuración del proxy

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP de Pomerium    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-pomerium-claim-email",        requiredHeaders: ["x-pomerium-jwt-assertion"],      },    },  },}

routes:  - from: https://openclaw.example.com    to: http://openclaw-gateway:18789    policy:      - allow:          or:            - email:                is: nick@example.com    pass_identity_headers: true

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP del proxy Caddy/sidecar    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

openclaw.example.com {    authenticate with oauth2_provider    authorize with policy1     reverse_proxy openclaw:18789 {        header_up X-Forwarded-User {http.auth.user.email}    }}

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP de nginx/oauth2-proxy    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-auth-request-email",      },    },  },}

location / {    auth_request /oauth2/auth;    auth_request_set $user $upstream_http_x_auth_request_email;     proxy_pass http://openclaw:18789;    proxy_set_header X-Auth-Request-Email $user;    proxy_http_version 1.1;    proxy_set_header Upgrade $http_upgrade;    proxy_set_header Connection "upgrade";}

{  gateway: {    bind: "lan",    trustedProxies: ["172.17.0.1"], // IP del contenedor de Traefik    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

Configuración mixta de tokens

El inicio del Gateway rechaza la autenticación mediante proxy de confianza si también hay configurado un token compartido (gateway.auth.token u OPENCLAW_GATEWAY_TOKEN). Ambos son mutuamente excluyentes porque un token compartido permitiría a los clientes del mismo host autenticarse mediante una ruta completamente distinta de la identidad verificada por el proxy que este modo debe exigir.

Si el inicio falla con un error como gateway auth mode is trusted-proxy, but a shared token is also configured:

• Elimine el token compartido cuando use el modo de proxy de confianza, o
• Cambie gateway.auth.mode a "token" si pretende usar autenticación basada en tokens.

Las cabeceras de identidad de proxy de confianza procedentes de local loopback también producen un rechazo seguro: los clientes del mismo host no se autentican silenciosamente como usuarios del proxy. Los clientes internos de OpenClaw que omiten el proxy pueden autenticarse con gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. La alternativa mediante token sigue sin admitirse intencionadamente en el modo de proxy de confianza.

Lista de comprobación de seguridad

Antes de habilitar la autenticación mediante proxy de confianza, compruebe lo siguiente:

• [ ] El proxy es la única ruta: El puerto del Gateway está protegido por un cortafuegos frente a todo excepto su proxy.
• [ ] trustedProxies es mínimo: Solo contiene las IP reales de sus proxies, no subredes completas.
• [ ] El origen local loopback del proxy es intencionado: La autenticación mediante proxy de confianza produce un rechazo seguro para solicitudes cuyo origen sea local loopback, salvo que gateway.auth.trustedProxy.allowLoopback se habilite explícitamente para un proxy del mismo host.
• [ ] El proxy elimina las cabeceras: Su proxy sobrescribe, en lugar de anexar, las cabeceras x-forwarded-* de los clientes.
• [ ] Terminación TLS: Su proxy gestiona TLS; los usuarios se conectan mediante HTTPS.
• [ ] allowedOrigins es explícito: La interfaz de control que no use local loopback utiliza un valor explícito de gateway.controlUi.allowedOrigins.
• [ ] allowUsers está configurado (recomendado): Restrinja el acceso a usuarios conocidos en lugar de permitirlo a cualquier usuario autenticado.
• [ ] No hay una configuración mixta de tokens: No configure simultáneamente gateway.auth.token y gateway.auth.mode: "trusted-proxy".
• [ ] La alternativa de contraseña local es privada: Si configura gateway.auth.password para clientes internos directos, mantenga el puerto del Gateway protegido por un cortafuegos para que los clientes remotos ajenos al proxy no puedan acceder directamente a él.

Auditoría de seguridad

openclaw security audit marca la autenticación mediante proxy de confianza con un hallazgo de gravedad crítica. Esto es intencionado; sirve para recordarle que está delegando la seguridad en la configuración de su proxy.

La auditoría comprueba:

• El aviso o recordatorio crítico base gateway.trusted_proxy_auth.
• La ausencia de la configuración trustedProxies.
• La ausencia de la configuración userHeader.
• Un valor allowUsers vacío (permite el acceso a cualquier usuario autenticado).
• La habilitación de allowLoopback para orígenes de proxy del mismo host.

También se aplican hallazgos independientes que no son específicos de los proxies de confianza siempre que la interfaz de control esté expuesta: un valor comodín o ausente de gateway.controlUi.allowedOrigins, y la alternativa de origen mediante la cabecera Host.

Solución de problemas

Migración desde la autenticación mediante token

Temas relacionados

• Configuración — referencia de configuración
• Ámbitos del operador — roles, ámbitos y comprobaciones de aprobación
• Acceso remoto — otros patrones de acceso remoto
• Seguridad — guía completa de seguridad
• Tailscale — alternativa más sencilla para el acceso exclusivo mediante redes Tailscale