Autenticación mediante proxy de confianza

Cuándo usarlo

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

Cuándo NO usarlo

• El proxy no autentica a los usuarios (solo es un terminador TLS o un balanceador de carga).
• Existe alguna ruta al Gateway que evita el proxy (aperturas en el cortafuegos, acceso desde la red interna).
• No se sabe con certeza si el proxy elimina o sobrescribe correctamente los encabezados reenviados.
• Solo se necesita acceso personal para un único usuario (considere en su lugar Tailscale Serve + bucle invertido).

Cómo funciona

Configuración

{  gateway: {    // De forma predeterminada, la autenticación mediante proxy de confianza espera que la IP de origen del proxy no sea de bucle invertido    bind: "lan",     // CRÍTICO: Añada aquí únicamente las IP del 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 bucle invertido en el mismo host tras habilitarlo explícitamente        allowLoopback: false,         // Opcional: permitir que los usuarios autenticados por el proxy registren nuevos dispositivos de navegador        deviceAutoApprove: {          enabled: false,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

Referencia de configuración

Aprobación automática de dispositivos

La autenticación mediante proxy de confianza puede utilizar opcionalmente la identidad del proxy como límite de aprobación para nuevos dispositivos de navegador:

{  gateway: {    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",        allowUsers: ["operator@example.com"],        deviceAutoApprove: {          enabled: true,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

El valor predeterminado es enabled: false. Cuando se habilita, se aplican todas estas reglas:

1. El WebSocket debe haberse autenticado mediante el método trusted-proxy con una identidad de usuario no vacía que haya superado allowUsers cuando haya una lista de usuarios permitidos configurada. Las conexiones mediante token, contraseña, Tailscale y sin autenticar nunca utilizan esta política.
2. Solo se puede aprobar automáticamente un nuevo dispositivo de navegador de la interfaz de control o WebChat. Cualquier solicitud para un dispositivo existente, incluida una ampliación de ámbitos, permanece pendiente de aprobación manual mediante openclaw devices approve <requestId>.
3. El dispositivo se aprueba con el rol operator. Si la solicitud de conexión incluye ámbitos, la concesión corresponde a la intersección exacta entre los ámbitos solicitados y deviceAutoApprove.scopes. Si la solicitud omite los ámbitos, se concede la lista configurada; cuando se omite esa lista, los valores predeterminados son operator.read, operator.write y operator.approvals. A continuación, la concesión resultante también queda limitada por el encabezado de proxy x-openclaw-scopes de la conexión, si está presente, de modo que un proxy que restrinja los ámbitos de un usuario también limite la concesión persistente del dispositivo, no solo la sesión; un encabezado presente pero vacío no concede ningún ámbito. Este límite se aplica incluso cuando el cliente omite su propia lista de ámbitos.
4. operator.admin solo se permite si figura explícitamente en deviceAutoApprove.scopes. Cuando se incluye, cada usuario autenticado por el proxy puede solicitar y recibir automáticamente privilegios administrativos completos en un nuevo dispositivo de navegador; las solicitudes sin ámbitos reciben automáticamente privilegios administrativos completos. openclaw security audit informa del hallazgo CRÍTICO gateway.trusted_proxy_device_auto_approve_admin, y el Gateway registra una advertencia una vez durante el inicio. Es preferible realizar la aprobación administrativa manual mediante openclaw devices approve o openclaw devices rotate hasta que estén disponibles los roles por identidad.

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 identidad de emparejamiento del dispositivo.

Implicaciones para 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 vacía la lista de ámbitos solicitados y la convierte en [] para que una sesión que no esté vinculada a un dispositivo o token emparejado y aprobado no pueda autodeclarar permisos.
• Si los métodos fallan con missing scope después de establecer correctamente una conexión WebSocket, utilice HTTPS para que el navegador pueda generar la identidad del dispositivo y completar el emparejamiento. Consulte HTTP no seguro de la interfaz de control.
• Las configuraciones antiguas que todavía contienen la clave retirada gateway.controlUi.dangerouslyDisableDeviceAuth=true utilizan la migración de actualización de la interfaz de control limitada.

Limitación de ámbitos mediante el proxy inverso: si el 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 entre los ámbitos solicitados y los declarados. Este encabezado no concede ámbitos; únicamente restringe los que puede tener la sesión. Cuando deviceAutoApprove.enabled es verdadero, el mismo límite también se aplica a la concesión persistente del dispositivo escrita por la aprobación automática de dispositivos, de modo que un dispositivo aprobado automáticamente nunca tenga más ámbitos que los declarados por el proxy.

Implicaciones:

• El emparejamiento deja de ser el control principal para el acceso a la interfaz de control sin dispositivo. Cuando deviceAutoApprove.enabled es verdadero, la identidad del proxy también se convierte en el control de aprobación para registrar nuevos dispositivos de navegador.
• La política de autenticación del proxy inverso y allowUsers se convierten en el control de acceso efectivo.
• Mantenga el acceso de entrada al Gateway restringido únicamente a las IP de proxy de confianza (gateway.trustedProxies + cortafuegos).

Los clientes WebSocket personalizados no son sesiones de la interfaz de control. La entrada de actualización retirada de la interfaz de control no concede acceso temporal a clientes arbitrarios client.mode: "backend" ni con formato de CLI. La automatización personalizada debe utilizar la identidad y el emparejamiento de dispositivos, la ruta auxiliar reservada del backend local directo client.id: "gateway-client" o el Plugin RPC HTTP de administración cuando sea 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 contiene identidad, por lo que los clientes pueden declarar opcionalmente ámbitos de operador con 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 el comportamiento de 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 contienen identidad recurren al conjunto estándar de ámbitos predeterminados del operador (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Las rutas HTTP de plugins con autenticación del Gateway son más restrictivas de forma predeterminada: cuando x-openclaw-scopes está ausente, su ámbito de ejecución recurre únicamente a operator.write.
• Las solicitudes HTTP con origen en el navegador deben seguir superando gateway.controlUi.allowedOrigins (o el modo alternativo deliberado mediante el encabezado Host), incluso después de que la autenticación mediante proxy de confianza se complete correctamente.

Regla práctica: envíe x-openclaw-scopes explícitamente cuando quiera que una solicitud mediante proxy de confianza sea más restrictiva que los valores 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",      },    },  },}

Orientación para el despliegue

• Comience primero con una antigüedad máxima corta (por ejemplo, max-age=300) mientras valida el tráfico.
• Aumente a valores de larga duración (por ejemplo, max-age=31536000) solo cuando tenga un alto grado de confianza.
• Añada includeSubDomains solo si todos los subdominios están preparados para HTTPS.
• Use la precarga solo si cumple deliberadamente los requisitos de precarga para todo el conjunto de dominios.
• El desarrollo local limitado al bucle invertido 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 de Caddy/proxy auxiliar    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 o OPENCLAW_GATEWAY_TOKEN). Ambos son mutuamente excluyentes porque un token compartido permitiría a los clientes del mismo host autenticarse mediante una ruta completamente diferente de la identidad verificada por el proxy que este modo está diseñado para 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 mediante tokens.

Los encabezados de identidad del proxy de confianza en el bucle invertido siguen produciendo un fallo seguro: los clientes del mismo host no se autentican silenciosamente como usuarios del proxy. En su lugar, los clientes internos de OpenClaw que omitan el proxy pueden autenticarse con gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. El uso alternativo de tokens sigue sin admitirse de forma intencionada en el modo de proxy de confianza.

Lista de comprobación de seguridad

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

• [ ] El proxy es la única ruta: El puerto del Gateway está protegido mediante un cortafuegos frente a todo excepto el proxy.
• [ ] trustedProxies es mínimo: Solo incluye las IP reales de los proxies, no subredes completas.
• [ ] El origen del proxy de bucle invertido es deliberado: La autenticación mediante proxy de confianza produce un fallo seguro para las solicitudes originadas en el bucle invertido, a menos que gateway.auth.trustedProxy.allowLoopback se habilite explícitamente para un proxy del mismo host.
• [ ] El proxy elimina los encabezados: El proxy sobrescribe (no añade) los encabezados x-forwarded-* de los clientes.
• [ ] Terminación TLS: El proxy gestiona TLS; los usuarios se conectan mediante HTTPS.
• [ ] allowedOrigins es explícito: La interfaz de control fuera del bucle invertido usa gateway.controlUi.allowedOrigins explícito.
• [ ] allowUsers está configurado (recomendado): Restrinja el acceso a usuarios conocidos en lugar de permitir a cualquiera que esté autenticado.
• [ ] No hay una configuración mixta de tokens: No configure simultáneamente gateway.auth.token y gateway.auth.mode: "trusted-proxy".
• [ ] El uso alternativo de contraseñas locales es privado: Si configura gateway.auth.password para clientes internos directos, mantenga el puerto del Gateway protegido mediante un cortafuegos para que los clientes remotos que no usen el proxy no puedan acceder directamente.
• [ ] La aprobación automática de dispositivos es deliberada: Si deviceAutoApprove.enabled es verdadero, trate la seguridad de la cuenta del proxy inverso como el límite de inscripción de dispositivos y mantenga la lista de ámbitos concedidos sin privilegios de administración y al mínimo.

Auditoría de seguridad

openclaw security audit señala la autenticación mediante proxy de confianza con un hallazgo de gravedad crítica. Esto es intencionado; sirve para recordar que se está delegando la seguridad a la configuración del proxy.

La auditoría comprueba:

• Advertencia o recordatorio crítico de gateway.trusted_proxy_auth básico.
• Falta la configuración de trustedProxies.
• Falta la configuración de userHeader.
• allowUsers vacío (permite a cualquier usuario autenticado).
• allowLoopback habilitado para los orígenes de proxy del mismo host.
• Aprobación automática de dispositivos del navegador habilitada (delega el emparejamiento de nuevos dispositivos a la identidad del proxy).

También se aplican hallazgos independientes y no específicos del proxy de confianza cuando la interfaz de control está expuesta: gateway.controlUi.allowedOrigins con comodín o ausente y uso alternativo del origen mediante el encabezado Host.

Solución de problemas

Migración desde la autenticación mediante token

Contenido relacionado

• 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 de seguridad completa
• Tailscale — alternativa más sencilla para el acceso exclusivo desde la tailnet