Autenticación mediante proxy de confianza

# Cuándo usarlo

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

• Ejecutas OpenClaw detrás de un proxy consciente de identidad (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Tu proxy gestiona toda la autenticación y pasa la identidad del usuario mediante encabezados.
• Estás en un entorno de Kubernetes o contenedores donde el proxy es la única ruta al Gateway.
• Te encuentras con errores de WebSocket 1008 unauthorized porque los navegadores no pueden pasar tokens en cargas WS.

# Cuándo NO usarlo

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

# Cómo funciona

# Comportamiento de emparejamiento de Control UI

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

Implicaciones:

• El emparejamiento deja de ser la puerta principal para el acceso a Control UI en este modo.
• La política de autenticación de tu proxy inverso y allowUsers se convierten en el control de acceso efectivo.
• Mantén la entrada del Gateway bloqueada solo a IPs de proxy de confianza (gateway.trustedProxies + firewall).

# Configuración

{
  gateway: {
    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source by default
    bind: "lan",

    // 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: ["[email protected]", "[email protected]"],

        // Optional: allow a same-host loopback proxy after explicit opt-in
        allowLoopback: false,
      },
    },
  },
}

# Referencia de configuración

# Terminación TLS y HSTS

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

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

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

# Guía de despliegue

• Empieza primero con una duración máxima corta (por ejemplo, max-age=300) mientras validas el tráfico.
• Aumenta a valores de larga duración (por ejemplo, max-age=31536000) solo cuando la confianza sea alta.
• Agrega includeSubDomains solo si todos los subdominios están listos para HTTPS.
• Usa preload solo si cumples intencionalmente los requisitos de preload para todo tu conjunto de dominios.
• El desarrollo local solo con loopback no se beneficia de HSTS.

# Ejemplos de configuración de proxy

{
  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"],
      },
    },
  },
}

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

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Caddy/sidecar proxy IP
    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"], // nginx/oauth2-proxy IP
    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"], // Traefik container IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

# Configuración mixta de tokens

OpenClaw rechaza configuraciones ambiguas en las que tanto un gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN) como el modo trusted-proxy están activos al mismo tiempo. Las configuraciones mixtas de tokens pueden hacer que las solicitudes loopback se autentiquen silenciosamente por la ruta de autenticación equivocada.

Si ves un error mixed_trusted_proxy_token al iniciar:

• Elimina el token compartido al usar el modo de proxy de confianza, o
• Cambia gateway.auth.mode a "token" si quieres autenticación basada en tokens.

Los encabezados de identidad de proxy de confianza en loopback siguen fallando de forma cerrada: los llamadores en el mismo host no se autentican silenciosamente como usuarios del proxy. Los llamadores internos de OpenClaw que omiten el proxy pueden autenticarse con gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD en su lugar. La alternativa de token sigue sin admitirse intencionalmente en modo de proxy de confianza.

# Encabezado de ámbitos de operador

La autenticación de proxy de confianza es un modo HTTP portador de identidad, por lo que los llamadores pueden declarar opcionalmente ámbitos de operador con x-openclaw-scopes.

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 ningún ámbito de operador.
• Cuando el encabezado está ausente, las API HTTP normales portadoras de identidad recurren al conjunto estándar de ámbitos de operador predeterminados.
• Las rutas HTTP de Plugin con autenticación de Gateway son más estrechas de forma predeterminada: cuando x-openclaw-scopes está ausente, su ámbito de tiempo de ejecución recurre a operator.write.
• Las solicitudes HTTP con origen de navegador aún deben pasar gateway.controlUi.allowedOrigins (o el modo deliberado de alternativa con encabezado Host) incluso después de que la autenticación de proxy de confianza tenga éxito.

Regla práctica: envía x-openclaw-scopes explícitamente cuando quieras que una solicitud de proxy de confianza sea más estrecha que los valores predeterminados, o cuando una ruta de Plugin con autenticación de Gateway necesite algo más fuerte que el ámbito de escritura.

# Lista de comprobación de seguridad

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

• [ ] El proxy es la única ruta: El puerto del Gateway está protegido por firewall frente a todo excepto tu proxy.
• [ ] trustedProxies es mínimo: Solo las IP reales de tu proxy, no subredes completas.
• [ ] La fuente de proxy loopback es deliberada: La autenticación trusted-proxy falla de forma cerrada para solicitudes con fuente loopback a menos que gateway.auth.trustedProxy.allowLoopback esté habilitado explícitamente para un proxy en el mismo host.
• [ ] El proxy elimina encabezados: Tu proxy sobrescribe (no agrega) los encabezados x-forwarded-* de los clientes.
• [ ] Terminación TLS: Tu proxy maneja TLS; los usuarios se conectan mediante HTTPS.
• [ ] allowedOrigins es explícito: La Control UI que no usa loopback utiliza gateway.controlUi.allowedOrigins explícito.
• [ ] allowUsers está configurado (recomendado): Restringe a usuarios conocidos en lugar de permitir a cualquier persona autenticada.
• [ ] Sin configuración mixta de tokens: No configures tanto gateway.auth.token como gateway.auth.mode: "trusted-proxy".
• [ ] La alternativa de contraseña local es privada: Si configuras gateway.auth.password para llamadores directos internos, mantén el puerto del Gateway protegido por firewall para que los clientes remotos que no pasan por el proxy no puedan acceder directamente.

# Auditoría de seguridad

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

La auditoría comprueba:

• Advertencia/recordatorio crítico base gateway.trusted_proxy_auth
• Falta la configuración de trustedProxies
• Falta la configuración de userHeader
• allowUsers vacío (permite cualquier usuario autenticado)
• allowLoopback habilitado para fuentes de proxy en el mismo host
• Política de origen del navegador comodín o ausente en superficies expuestas de la Control UI

# Solución de problemas

# Migración desde autenticación por token

Si estás migrando desde autenticación por token a trusted-proxy:

# Relacionado

• Configuración — referencia de configuración
• Acceso remoto — otros patrones de acceso remoto
• Seguridad — guía completa de seguridad
• Tailscale — alternativa más simple para acceso solo por tailnet