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

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

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

• 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.

• 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).

​

Encabezado de ámbitos del operador

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

• 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.

​

Terminación TLS y HSTS

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

• 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.

​

Lista de comprobación de seguridad

• 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

• 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).

​

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