Configura la autenticación Trusted Proxy en OpenClaw

¿Alguna vez has pasado horas peleando con errores de WebSocket porque tu proxy no pasa los tokens correctamente? Configurar la autenticación detrás de un reverse proxy puede ser un dolor de cabeza, pero cuando lo haces bien, simplifica mucho la gestión de usuarios y centraliza la seguridad de tu infraestructura.

Si ya usas herramientas para gestionar la identidad en tu red, no tiene sentido duplicar el trabajo. Esta guía te explica cómo delegar esa responsabilidad a tu proxy de forma segura y directa.

Trusted Proxy Auth

⚠️ Función sensible para la seguridad. Este modo delega la autenticación por completo a tu reverse proxy. Una mala configuración puede exponer tu Gateway a accesos no autorizados. Lee esta página con cuidado antes de activarlo.

Cuándo usarlo

Usa el modo de autenticación trusted-proxy cuando:

• Ejecutas OpenClaw detrás de un identity-aware proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Tu proxy gestiona toda la autenticación y pasa la identidad del usuario mediante headers.
• Estás en un entorno de Kubernetes o contenedores donde el proxy es la única vía de acceso al Gateway.
• Tienes errores de WebSocket 1008 unauthorized porque los navegadores no pueden pasar tokens en los payloads de WS.

Cuándo NO usarlo

• Si tu proxy no autentica usuarios (solo es un terminador TLS o un balanceador de carga).
• Si existe alguna ruta hacia el Gateway que ignore el proxy (huecos en el firewall, acceso por red interna).
• Si no tienes seguridad de que tu proxy elimina o sobrescribe correctamente los headers reenviados.
• Si solo necesitas acceso personal para un único usuario (considera Tailscale Serve + loopback para una configuración más simple).

Cómo funciona

1. Tu reverse proxy autentica a los usuarios (OAuth, OIDC, SAML, etc.).
2. El proxy añade un header con la identidad del usuario autenticado (por ejemplo, x-forwarded-user: nick@example.com).
3. OpenClaw verifica que la solicitud provenga de una IP de proxy de confianza (configurada en gateway.trustedProxies).
4. OpenClaw extrae la identidad del usuario desde el header configurado.
5. Si todo coincide, la solicitud se autoriza.

Comportamiento de emparejamiento de Control UI

Cuando gateway.auth.mode = "trusted-proxy" está activo y la solicitud supera las verificaciones de proxy de confianza, las sesiones de WebSocket de Control UI pueden conectarse sin identidad de emparejamiento de dispositivo (pairing).

Implicaciones:

• El emparejamiento ya no es la barrera principal para el acceso a Control UI en este modo.
• La política de autenticación de tu reverse proxy y allowUsers se convierten en el control de acceso efectivo.
• Mantén el ingreso al Gateway bloqueado solo para IPs de proxies de confianza (gateway.trustedProxies + firewall).

Configuración

{
  gateway: {
    // Use loopback for same-host proxy setups; use lan/custom for remote proxy hosts
    bind: "loopback",

    // CRITICAL: Only add your proxy's IP(s) here
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Header containing authenticated user identity (required)
        userHeader: "x-forwarded-user",

        // Optional: headers that MUST be present (proxy verification)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Optional: restrict to specific users (empty = allow all)
        allowUsers: ["nick@example.com", "admin@company.org"],
      },
    },
  },
}

Si gateway.bind es loopback, incluye una dirección de proxy loopback en gateway.trustedProxies (127.0.0.1 o ::1).

Referencia de configuración

Campo	Requerido	Descripción
gateway.trustedProxies	Sí	Array de direcciones IP de proxies en los que confiar. Las solicitudes de otras IPs serán rechazadas.
gateway.auth.mode	Sí	Debe ser "trusted-proxy".
gateway.auth.trustedProxy.userHeader	Sí	Nombre del header que contiene la identidad del usuario autenticado.
gateway.auth.trustedProxy.requiredHeaders	No	Headers adicionales que deben estar presentes para que la solicitud sea de confianza.
gateway.auth.trustedProxy.allowUsers	No	Lista permitida de identidades de usuario. Si está vacía, permite a todos los usuarios autenticados.

Terminación TLS y HSTS

Usa un único punto de terminación TLS y aplica HSTS allí.

Patrón recomendado: terminación TLS en el proxy

Cuando tu reverse proxy gestiona HTTPS para https://control.example.com, configura Strict-Transport-Security en el proxy para ese dominio.

• Es ideal para despliegues orientados a internet.
• Mantiene el certificado y la política de endurecimiento HTTP en un solo lugar.
• OpenClaw puede permanecer en HTTP en loopback detrás del proxy.

Ejemplo de valor de header:

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

Terminación TLS en el Gateway

Si OpenClaw sirve HTTPS directamente (sin un proxy que termine TLS), configura:

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

strictTransportSecurity acepta un string con el valor del header, o false para desactivarlo explícitamente.

Guía de despliegue

• Comienza con un max-age corto (por ejemplo max-age=300) mientras validas el tráfico.
• Aumenta a valores de larga duración (por ejemplo max-age=31536000) solo cuando tengas total seguridad.
• Añade includeSubDomains solo si cada subdominio está listo para HTTPS.
• Usa preload solo si cumples intencionadamente los requisitos de precarga para todo tu conjunto de dominios.
• El desarrollo local solo en loopback no obtiene beneficios de HSTS.

Ejemplos de configuración de Proxy

Pomerium

Pomerium pasa la identidad en x-pomerium-claim-email (u otros headers de claims) y un JWT en x-pomerium-jwt-assertion.

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

Fragmento de configuración de Pomerium:

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

Caddy con OAuth

Caddy con el plugin caddy-security puede autenticar usuarios y pasar headers de identidad.

{
  gateway: {
    bind: "lan",
    trustedProxies: ["127.0.0.1"], // Caddy's IP (if on same host)
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

Fragmento de Caddyfile:

openclaw.example.com {
    authenticate with oauth2_provider
    authorize with policy1

    reverse_proxy openclaw:18789 {
        header_up X-Forwarded-User {http.auth.user.email}
    }
}

nginx + oauth2-proxy

oauth2-proxy autentica usuarios y pasa la identidad en x-auth-request-email.

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

Fragmento de configuración de nginx:

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";
}

Traefik con Forward Auth

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

Configuración de tokens mixtos

OpenClaw rechaza configuraciones ambiguas donde un gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN) y el modo trusted-proxy estén activos al mismo tiempo. Las configuraciones de tokens mixtos pueden causar que las solicitudes de loopback se autentiquen silenciosamente por la ruta de autenticación incorrecta.

Si ves un error mixed_trusted_proxy_token al arrancar:

• Elimina el token compartido cuando uses el modo trusted-proxy, o
• Cambia gateway.auth.mode a "token" si tu intención es usar autenticación basada en tokens.

La autenticación trusted-proxy en loopback también falla por defecto: quienes llamen desde el mismo host deben proporcionar los headers de identidad configurados a través de un proxy de confianza en lugar de ser autenticados silenciosamente.

Lista de verificación de seguridad

Antes de activar la autenticación trusted-proxy, verifica:

• El proxy es la única ruta: El puerto del Gateway está protegido por firewall contra todo excepto tu proxy.
• trustedProxies es mínimo: Solo las IPs reales de tu proxy, no subredes completas.
• El proxy limpia los headers: Tu proxy sobrescribe (no añade al final) los headers x-forwarded-* de los clientes.
• Terminación TLS: Tu proxy gestiona TLS; los usuarios se conectan vía HTTPS.
• allowUsers está configurado (recomendado): Restringe a usuarios conocidos en lugar de permitir a cualquiera que esté autenticado.
• Sin configuración de tokens mixtos: No configures gateway.auth.token y gateway.auth.mode: "trusted-proxy" a la vez.

Auditoría de seguridad

openclaw security audit marcará la autenticación trusted-proxy con un hallazgo de severidad crítica. Esto es intencionado: es un recordatorio de que estás delegando la seguridad a la configuración de tu proxy.

La auditoría verifica:

• Falta de configuración en trustedProxies.
• Falta de configuración en userHeader.
• allowUsers vacío (permite cualquier usuario autenticado).

Solución de problemas

”trusted_proxy_untrusted_source”

La solicitud no provino de una IP en gateway.trustedProxies. Revisa:

• ¿Es correcta la IP del proxy? (Las IPs de contenedores Docker pueden cambiar).
• ¿Hay un balanceador de carga delante de tu proxy?
• ¿Ha cambiado la IP del contenedor recientemente?
• Usa docker inspect o kubectl get pods -o wide para encontrar las IPs reales.

”trusted_proxy_user_missing”

El header de usuario estaba vacío o ausente. Revisa:

• ¿Está tu proxy configurado para pasar headers de identidad?
• ¿Es correcto el nombre del header? (No distingue mayúsculas, pero la ortografía importa).
• ¿Está el usuario realmente autenticado en el proxy?
• ¿Hay errores en los logs del proxy al procesar la identidad?

“trusted_proxy_missing_header_*”

Un header requerido no estaba presente. Revisa:

• La configuración de tu proxy para esos headers específicos.
• Si los headers están siendo eliminados en algún punto de la cadena.

”trusted_proxy_user_not_allowed”

El usuario está autenticado pero no aparece en allowUsers. Añádelo o elimina la lista permitida.

WebSocket sigue fallando

Asegúrate de que tu proxy:

• Soporta actualizaciones de WebSocket (Upgrade: websocket, Connection: upgrade).
• Pasa los headers de identidad en las solicitudes de actualización de WebSocket (no solo en HTTP).
• No tiene una ruta de autenticación separada para las conexiones WebSocket.

Migración desde Token Auth

Si te estás moviendo de autenticación por token a trusted-proxy:

1. Configura tu proxy para autenticar usuarios y pasar headers.
2. Prueba la configuración del proxy de forma independiente (curl con headers).
3. Actualiza la configuración de OpenClaw con la autenticación trusted-proxy.
4. Reinicia el Gateway.
5. Prueba las conexiones WebSocket desde la Control UI.
6. Ejecuta openclaw security audit y revisa los hallazgos.

Relacionado

• Security — guía completa de seguridad
• Configuration — referencia de configuración
• Remote Access — otros patrones de acceso remoto
• Tailscale — alternativa simple para acceso exclusivo vía tailnet

AI Setup Assistant