Autenticación por proxy de confianza en OpenClaw

La autenticación por proxy de confianza es el modo para gateways que están detrás de un proxy con reconocimiento de identidad: el proxy autentica a la persona, añade un encabezado con su identidad y el gateway confía en ese encabezado, pero solo si procede del proxy. La documentación empieza con una advertencia de que una mala configuración expone el gateway, y la mayor parte de la página es la lista de comprobaciones que hacen segura esa confianza. Aquí está, en el orden en que el gateway la evalúa.

Cuándo y cómo

• Úsalo detrás de Pomerium, Caddy con OAuth, nginx con oauth2-proxy o Traefik con forward auth, en entornos de contenedores donde el proxy es la única ruta, o cuando los navegadores reciben errores de WebSocket no autorizado porque no pueden pasar tokens en el handshake; no lo uses cuando el proxy solo termina TLS, cuando alguna ruta evita el proxy, cuando no estás seguro de que el proxy elimine los encabezados reenviados, o para un acceso personal de un solo usuario, donde una tailnet más loopback es más simple.
• El flujo: el proxy autentica al usuario, añade un encabezado de identidad como el encabezado de usuario reenviado, el gateway verifica que la solicitud procede de una dirección de proxy de confianza, lee los encabezados obligatorios y la identidad del usuario, y autoriza cuando la lista de usuarios permitidos, si está definida, incluye al usuario; la configuración se enlaza a la red local, enumera solo las direcciones o rangos del proxy, define el modo de autenticación, el encabezado de usuario, encabezados obligatorios opcionales, una lista de usuarios permitidos opcional, loopback desactivado de forma predeterminada y la aprobación automática de dispositivos desactivada de forma predeterminada.
• Reglas en tiempo de ejecución, en orden: el tráfico con forma de proxy se atribuye antes de la autenticación del gateway y debe proceder de un proxy de confianza con encabezados de dirección de cliente que resuelvan a un cliente que no sea loopback, o las rutas autenticadas por el gateway lo rechazan por falta de atribución de proxy; el proxy debe sobrescribir la cadena forwarded-for de forma segura, y el encabezado de dirección real solo se acepta cuando su respaldo está activado; las fuentes de loopback se rechazan salvo que la opción esté en true y loopback también figure como proxy de confianza; las fuentes que coinciden con una de las direcciones de interfaz del propio host se rechazan como protección contra la suplantación, y un fallo en el descubrimiento de interfaces también provoca el rechazo; después, los encabezados obligatorios y el encabezado de usuario deben estar presentes y no vacíos, y la lista de usuarios permitidos debe incluir al usuario.
• La evidencia de encabezados reenviados en una solicitud de loopback la descalifica del respaldo local directo por contraseña y del control por identidad de dispositivo, sin dejar de fallar en la autenticación por proxy de confianza; los clientes internos que no pasan por el proxy usan la contraseña del gateway, que el comando de estado selecciona automáticamente cuando no se indica otra URL; la lista de proxies de confianza acepta rangos de direcciones tal cual o en forma mapeada, y un prefijo mapeado que lo cubre todo sigue necesitando la opción de loopback para loopback.

Un token del Gateway no puede sustituir la autenticación por proxy.

Concesiones, aprobación automática y el encabezado de scopes

Los scopes por identidad dan a determinados usuarios verificados scopes solo de sesión sin ampliar la concesión de su dispositivo: la clave es la identidad del proxy o el inicio de sesión de la tailnet, los correos electrónicos coinciden sin distinguir mayúsculas de minúsculas, la concesión se une a los scopes autorizados del dispositivo y luego se limita con un encabezado de scopes explícito, y las conexiones por token, por contraseña y sin autenticación nunca la reciben. La aprobación automática de dispositivos, desactivada de forma predeterminada, usa la identidad del proxy como frontera de aprobación para nuevos dispositivos de operador de navegador y nativos y para las ampliaciones de scopes con la misma clave: solo cumplen los requisitos las conexiones por proxy de confianza con una identidad no vacía que haya superado la lista de permitidos, las conexiones con rol de nodo y las ampliaciones de rol nunca, los scopes solicitados se intersecan con la lista configurada (read, write, approvals y questions cuando no está definida, nunca ampliada), el encabezado de scopes del proxy también limita la concesión persistente, e incluir admin en la lista permite que cualquier usuario del proxy reciba un dispositivo con administración completa, algo que la auditoría de seguridad informa como crítico y sobre lo que el gateway advierte al arrancar. Las sesiones de la interfaz de control sin dispositivo no pueden declarar sus propios scopes: su lista se vacía y se aplica la concesión por identidad correspondiente; un fallo por scope faltante después de una conexión correcta significa que hay que recargar para que el navegador empareje su identidad de dispositivo. El encabezado de scopes declara scopes cuando está presente, no declara ninguno cuando está presente pero vacío, y recurre al conjunto de operador predeterminado cuando falta, mientras que las rutas de plugins con autenticación del gateway recurren solo a write.

TLS, tokens mixtos y la auditoría

• Termina TLS una sola vez y define allí el encabezado de transporte estricto: en el proxy para despliegues expuestos a internet, con el gateway en loopback detrás de él, o en el gateway con TLS activado y el encabezado de seguridad de transporte estricto cuando sirve HTTPS por sí mismo; empieza con un max age corto, auméntalo solo cuando tengas confianza, añade el indicador de subdominios solo cuando todos los subdominios estén listos, y omítelo para el desarrollo solo en loopback.
• El arranque rechaza la autenticación por proxy de confianza cuando también hay configurado un token compartido, porque un token permitiría a los llamadores del mismo host autenticarse por una ruta distinta de la identidad verificada por el proxy; elimina el token o cambia el modo, y recuerda que los encabezados de identidad en loopback siguen fallando en modo cerrado y que el respaldo por token no se admite a propósito.
• La auditoría de seguridad marca el modo como crítico por diseño y comprueba si falta la lista de proxies de confianza, si falta el encabezado de usuario, si la lista de usuarios permitidos está vacía, si la opción de loopback está activada y si la aprobación automática de dispositivos está activada; la lista de verificación añade que el proxy sea la única ruta, que la lista de confianza sea mínima, que el proxy sobrescriba los encabezados reenviados y reconstruya la cadena forwarded-for, que los orígenes permitidos sean explícitos para una interfaz de control que no esté en loopback, y que cualquier respaldo por contraseña local permanezca privado detrás del firewall.

La guía de scopes de operador de OpenClaw explica el modelo de scopes que alimentan estas concesiones y OpenClaw en Tailscale, la alternativa más simple para un acceso solo por tailnet.

Cómo leer los códigos de rechazo

La sección de solución de problemas explica cada rechazo: una fuente no confiable significa que la solicitud no procedía de una dirección de proxy de la lista, algo que cambia cuando los contenedores se reinician; una fuente de loopback significa un proxy en el mismo host sin la opción activada deliberadamente; una fuente de interfaz local significa que un proceso en el host del gateway envía encabezados de identidad directamente o que el proxy comparte el espacio de nombres de red del host; un usuario ausente significa que el encabezado falta o tiene un nombre incorrecto; un usuario no permitido significa que la cuenta está autenticada pero no figura en la lista de permitidos, y la documentación advierte que no se elimine la lista como solución provisional; un origen no permitido significa que el origen del navegador no superó la comprobación de la interfaz de control. El mensaje de que se requiere autenticación por proxy indica una identidad rechazada, no una caída de la red, y la solución es iniciar sesión en el proxy en lugar de enviar encabezados desde el navegador. La migración desde la autenticación por token consta de seis pasos: configurar el proxy, probarlo de forma independiente, actualizar la configuración del gateway, reiniciar, probar el WebSocket desde la interfaz de control y ejecutar la auditoría. El acceso remoto de OpenClaw compara los demás patrones de acceso remoto y el emparejamiento de OpenClaw, el flujo de dispositivos al que sustituye la aprobación automática.

En Diali

En Diali, a cada gateway de cliente se accede a través del ingress de la plataforma, con la configuración del motor generada desde el panel y reemplazada en cada versión, así que este modo no es algo que un cliente tenga que montar a mano. OpenClaw alojado en Diali describe el asistente alojado y la seguridad de Diali, la frontera alrededor de cada motor.

• Confía en el encabezado solo si procede de direcciones de proxy de la lista.
• Las fuentes de loopback y de las propias interfaces fallan en modo cerrado.
• El encabezado de scopes restringe; las concesiones por identidad añaden, solo para la sesión.