Proteger apps con SSO usando oauth2-proxy
Implementa autenticacion delegada con oauth2-proxy para proteger servicios sin login propio. Aprende a configurar auth_request en Nginx o Traefik evitando errores de cookies.
Autenticación delegada: cómo obtener SSO en una aplicación sin inicio de sesión
oauth2-proxy proporciona inicio de sesión único a una aplicación que no tiene un sistema de inicio de sesión propio. Funciona porque el proxy inverso situado delante de la aplicación detiene todas las solicitudes, pregunta a oauth2-proxy si la solicitud incluye una sesión válida y sólo la reenvía al backend cuando la respuesta es afirmativa. El código de la aplicación no cambia porque la aplicación nunca ve esta comprobación.
La comprobación añade una solicitud HTTP. El proxy envía una copia de las cabeceras de la solicitud entrante a /oauth2/auth y lee el código de estado. Un 202 indica que la comprobación se ha superado, por lo que el proxy reenvía la solicitud original a la aplicación. Un 401 indica que no hay una sesión válida, por lo que el proxy redirige el navegador a /oauth2/sign_in, que muestra una página de inicio de sesión de forma predeterminada. /oauth2/start inicia un inicio de sesión OpenID Connect (OIDC) en el proveedor de identidad; skip_provider_button = true hace que /oauth2/sign_in lo inicie automáticamente. OIDC es la capa de identidad construida sobre OAuth 2.0, y el proveedor es el sistema que ya utiliza para los inicios de sesión.
Este patrón tiene un nombre en cada proxy inverso. Nginx llama a la directiva auth_request. Traefik llama middleware a forwardAuth. Caddy lo denomina forward_auth. El servicio que responde a la subsolicitud también puede sustituirse. oauth2-proxy es la opción habitual porque habla OIDC directamente y no necesita su propia base de datos.
Dibuja el límite de confianza antes de escribir cualquier configuración
Tras una comprobación correcta, oauth2-proxy devuelve la identidad en las cabeceras de respuesta y el proxy inverso las copia en la solicitud dirigida al upstream. Con set_xauthrequest habilitado, obtienes X-Auth-Request-User y X-Auth-Request-Email. La aplicación lee esas cabeceras y confía en ellas.
Ese es todo el modelo de seguridad, así que hay que expresar claramente la consecuencia. Cualquier proceso que pueda abrir una conexión TCP al puerto de la aplicación puede establecer esas cabeceras por sí mismo y hacerse pasar por cualquier usuario. Un único curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/ permite eludir completamente el control si llega directamente a la aplicación.
Por tanto, la aplicación no debe ser accesible excepto a través del proxy. En Docker Compose, elimina la asignación ports: del servicio de la aplicación y déjalo en la red interna, de modo que sólo el contenedor del proxy pueda conectarse a él. En un host independiente, vincula la aplicación a 127.0.0.1:3000 en lugar de 0.0.0.0:3000. Después, comprueba qué has expuesto realmente:
sudo ss -tlnp | grep 3000Una línea que muestre 0.0.0.0:3000 significa que la aplicación responde en la IP pública y que el control de acceso es decorativo. 127.0.0.1:3000 es lo que necesitas. Una regla de firewall es una segunda capa útil, pero la dirección de enlace es la que seguirá vigente si otra herramienta vacía tu conjunto de reglas.
Instalar oauth2-proxy
En octubre de 2026, la versión actual es v7.15.5, publicada el 1 de octubre de 2026. Corrige dos avisos de seguridad críticos. Uno de ellos permite eludir skip_auth_routes y afecta a todas las versiones posteriores a v7.5.0. No instale una versión anterior. Instale el binario y verifique la descarga:
cd /tmp
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
sha256sum -c oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
tar -xzf oauth2-proxy-v7.15.5.linux-amd64.tar.gz
sudo install -m 755 oauth2-proxy-v7.15.5.linux-amd64/oauth2-proxy /usr/local/bin/oauth2-proxy
oauth2-proxy --versionsha256sum -c debe mostrar una línea que termine en OK. Si muestra FAILED, deténgase y vuelva a descargarlo en lugar de ejecutar el binario.
En Docker, la imagen es quay.io/oauth2-proxy/oauth2-proxy y debe fijar la etiqueta: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5. Si la deja en latest, una docker compose pull rutinaria se convierte en una actualización no planificada del proceso que protege todas las aplicaciones del servidor.
Generar el secreto de la cookie
La cookie de sesión está cifrada y cookie_secret es la clave. La clave de cifrado debe tener exactamente 16, 24 o 32 bytes, porque se convierte en una clave AES (advanced encryption standard). oauth2-proxy acepta un valor base64 seguro para URL que se decodifique en una de esas longitudes, o un secreto sin codificar de una de esas longitudes. De lo contrario, no se inicia y muestra un error de arranque que identifica el secreto de la cookie. El comando siguiente genera un valor de 44 caracteres que codifica una clave de 32 bytes.
openssl rand -base64 32 | tr -- '+/' '-_'El tr no es un detalle estético. Convierte base64 estándar al alfabeto seguro para URL que oauth2-proxy usa al decodificar el secreto.
Aplique estas dos reglas a este valor. Use un secreto diferente en cada despliegue. Si ejecuta más de una instancia de oauth2-proxy detrás del mismo dominio, asígneles el mismo secreto. Una cookie cifrada por una instancia debe poder ser leída por las demás.
Escriba la configuración de oauth2-proxy
Mantenga la configuración en un archivo en lugar de usar una línea de comandos larga, para que el secreto del cliente nunca aparezca en la salida de ps.
# /etc/oauth2-proxy/oauth2-proxy.cfg
http_address = "127.0.0.1:4180"
reverse_proxy = true
provider = "oidc"
oidc_issuer_url = "https://id.example.com/application/o/myapp/"
client_id = "REPLACE_ME"
client_secret = "REPLACE_ME"
redirect_url = "https://app.example.com/oauth2/callback"
cookie_secret = "REPLACE_ME"
cookie_secure = true
cookie_domains = [".example.com"]
whitelist_domains = [".example.com"]
email_domains = ["*"]
set_xauthrequest = true
upstreams = ["static://202"]reverse_proxy = true indica a oauth2-proxy que confíe en las cabeceras X-Forwarded-* enviadas por el proxy situado delante. Sin esta opción, oauth2-proxy considera que la dirección del cliente es la dirección del propio proxy y puede determinar incorrectamente si la solicitud llegó mediante HTTPS.
trusted_proxy_ips limita los pares que pueden proporcionar esas cabeceras. De forma predeterminada, confía en cualquier origen. Aquí sólo es seguro porque http_address mantiene oauth2-proxy en 127.0.0.1. Si oauth2-proxy escucha en una red Docker, configúrelo con la dirección de su reverse proxy.
upstreams = ["static://202"] hace que oauth2-proxy responda con 202 a una solicitud autenticada sin actuar como proxy. Esto es exactamente lo que necesita forward auth, porque el reverse proxy se encarga de reenviar la solicitud. La otra forma de despliegue coloca oauth2-proxy directamente en la ruta de la solicitud con upstreams = ["http://127.0.0.1:3000"] y sin auth_request. Es más sencilla para una aplicación, pero no escala a diez.
email_domains = ["*"] admite cualquier dirección que su proveedor autentique. Limítelo a su propio dominio o, mejor, restrinja el acceso mediante una asociación de grupo en el proveedor, porque ahí ya administra a los usuarios.
Ejecútelo con systemd usando un usuario específico:
# /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network-online.target
Wants=network-online.target
[Service]
User=oauth2-proxy
Group=oauth2-proxy
ExecStart=/usr/local/bin/oauth2-proxy --config=/etc/oauth2-proxy/oauth2-proxy.cfg
Restart=on-failure
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true
[Install]
WantedBy=multi-user.targetsudo useradd --system --no-create-home --shell /usr/sbin/nologin oauth2-proxy
sudo install -d -m 750 /etc/oauth2-proxy
sudo chown -R oauth2-proxy:oauth2-proxy /etc/oauth2-proxy
sudo chmod 600 /etc/oauth2-proxy/oauth2-proxy.cfg
sudo systemctl daemon-reload
sudo systemctl enable --now oauth2-proxy
curl -s http://127.0.0.1:4180/ping/ping al mostrar OK indica que el proceso se inició y cargó su configuración. Es el propio endpoint de estado de oauth2-proxy y nunca solicita una sesión. Si no responde, lea journalctl -u oauth2-proxy -n 50, porque una URL de issuer incorrecta y un secreto de cookie con una longitud incorrecta provocan un error durante el inicio y ambos casos quedan registrados.
Registre la URI de redirección en su proveedor
Cree una aplicación OIDC en su proveedor y establezca su URI de redirección exactamente como redirect_url en la configuración: https://app.example.com/oauth2/callback. Exactamente significa que el esquema, el host, el puerto y la ruta deben coincidir carácter por carácter. Una barra final hace que sea una URI diferente.
Este es el fallo más común de toda la configuración. Se produce antes de que oauth2-proxy intervenga. El proveedor rechaza la solicitud de autorización y muestra su propia página de error, por lo que no aparece nada en el registro de oauth2-proxy. La indicación está en la barra de direcciones: el navegador todavía está en el dominio del proveedor y la cadena de consulta contiene error=invalid_request o la página muestra directamente redirect_uri. Si ocurre esto, corrija el registro de la aplicación en el proveedor, no la configuración del proxy.
Copie la URL del emisor desde el proveedor en lugar de escribirla manualmente. oauth2-proxy añade /.well-known/openid-configuration a oidc_issuer_url y obtiene ese documento de descubrimiento durante el arranque. Compruébelo primero:
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400Un JSON que contenga una clave authorization_endpoint es una primera comprobación. El issuer del documento también debe coincidir exactamente con oidc_issuer_url. Un 404 o una página de error HTML indican que la URL es incorrecta. oauth2-proxy no podrá arrancar porque recibirá el mismo 404. Si todavía no ha elegido un proveedor, la comparación de Keycloak, Authentik y Zitadel explica las diferencias, y cómo ejecutar Authentik como su propio servidor SSO describe la parte del proveedor de esta misma configuración.
Nginx: auth_request
Nginx realiza la autenticación delegada con auth_request. Esta directiva ejecuta una subsolicitud interna y toma una decisión según su código de estado.
# in the http context, next to your other maps
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name app.example.com;
location /oauth2/ {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Auth-Request-Redirect $request_uri;
}
location = /oauth2/auth {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Uri $request_uri;
proxy_set_header Content-Length "";
proxy_pass_request_body off;
}
location / {
auth_request /oauth2/auth;
error_page 401 = @oauth2_signin;
auth_request_set $user $upstream_http_x_auth_request_user;
auth_request_set $email $upstream_http_x_auth_request_email;
proxy_set_header X-User $user;
proxy_set_header X-Email $email;
auth_request_set $auth_cookie $upstream_http_set_cookie;
add_header Set-Cookie $auth_cookie;
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
location @oauth2_signin {
return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
}
}Hay tres detalles importantes. proxy_pass_request_body off con un Content-Length vacío impide que nginx reenvíe el cuerpo de la solicitud al endpoint de autenticación. Ese endpoint sólo necesita las cabeceras.
El par auth_request_set $auth_cookie y add_header Set-Cookie devuelve una cookie de sesión renovada al navegador. Si se omite, cookie_refresh no hace nada de forma silenciosa, porque nginx descarta el Set-Cookie de la subsolicitud y el navegador conserva el valor antiguo hasta que caduque la sesión. Este par gestiona una cookie. Las cookies de sesión divididas requieren un tratamiento adicional para las demás partes o el almacenamiento de sesiones en Redis.
error_page 401 = @oauth2_signin convierte una comprobación fallida en un inicio de sesión. Sin esta directiva, un visitante no autenticado recibe una página 401 Authorization Required básica y no tiene ninguna forma de continuar.
Pruebe siempre la configuración antes de recargarla:
sudo nginx -t && sudo systemctl reload nginxSi las directivas relacionadas son nuevas para usted, la anatomía de una configuración de proxy inverso de nginx explica la capa subyacente.
Traefik: middleware forwardAuth
Traefik necesita dos middlewares para esta tarea. Uno ejecuta la comprobación. El otro sirve la página de inicio de sesión cuando la comprobación falla.
# dynamic configuration
http:
middlewares:
oauth-auth:
forwardAuth:
address: https://oauth.example.com/oauth2/auth
trustForwardHeader: true
oauth-errors:
errors:
status:
- "401-403"
service: oauth-backend
query: "/oauth2/sign_in?rd={url}"Asocie ambos al router que expone la aplicación, con oauth-errors antes de oauth-auth, y publique oauth2-proxy en su propio router en oauth.example.com, porque el navegador debe acceder a /oauth2/sign_in y /oauth2/callback sin pasar por la comprobación. Para este host de inicio de sesión independiente, establezca redirect_url en https://oauth.example.com/oauth2/callback y registre esa URI con el proveedor.
Con la configuración anterior de oauth2-proxy, /oauth2/sign_in muestra una página de inicio de sesión. Para redirigir automáticamente, establezca skip_provider_button = true en oauth2-proxy y añada statusRewrites: {"401": 302} en la configuración de errors de Traefik. Sin esa reescritura, Traefik devuelve la redirección automática con el estado 401 y el navegador no la sigue. La reescritura por sí sola no inicia el flujo de inicio de sesión.
trustForwardHeader: true confía en las cabeceras X-Forwarded-* recibidas; Traefik proporciona el host y la URI originales a oauth2-proxy. Esta opción está obsoleta en la documentación actual de Traefik. Establezca whitelist_domains para incluir también ese host. De lo contrario, oauth2-proxy elimina el parámetro rd como medida contra el riesgo de redirección abierta y todos llegan a / después de iniciar sesión. Un servidor Traefik suele exponer varias aplicaciones a la vez, y encaminar varias aplicaciones de Docker Compose mediante una sola instancia de Traefik muestra la estructura de routers en la que se integra.
Caddy: forward_auth
app.example.com {
handle /oauth2/* {
reverse_proxy 127.0.0.1:4180 {
header_up X-Real-IP {remote_host}
header_up X-Forwarded-Uri {uri}
}
}
handle {
forward_auth 127.0.0.1:4180 {
uri /oauth2/auth
header_up X-Real-IP {remote_host}
copy_headers X-Auth-Request-User X-Auth-Request-Email
@error status 401
handle_response @error {
redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
}
}
reverse_proxy 127.0.0.1:3000
}
}El orden es importante. El bloque /oauth2/* va primero y no incluye ningún forward_auth, porque un visitante que no ha iniciado sesión debe poder acceder a las rutas de inicio de sesión y de callback. Si coloca la comprobación delante de esas rutas, el inicio de sesión se redirige a sí mismo hasta que el navegador abandona el proceso.
copy_headers transfiere la identidad a la solicitud enviada al upstream y sólo genera valores cuando oauth2-proxy se ejecuta con set_xauthrequest = true. Elegir entre los proxies es otra cuestión, y la comparación entre nginx, Caddy y Traefik la explica.
¿Por qué el inicio de sesión vuelve a mostrar la página de inicio de sesión?
Inicia sesión en el proveedor, este te redirige de vuelta y oauth2-proxy te devuelve a la página de inicio de sesión. El bucle indica que oauth2-proxy no acepta una sesión válida en la siguiente petición. La cookie de sesión puede faltar, o puede estar presente y no superar la validación, por ejemplo, cuando las instancias usan secretos de cookie diferentes. Abre las herramientas de desarrollo del navegador, busca la petición a /oauth2/callback que sigue a la redirección de vuelta desde el proveedor y lee su cabecera de respuesta Set-Cookie. La cookie que se establece allí y falta en la siguiente petición es la que el navegador está rechazando. Si está presente, revisa el registro del servidor para buscar errores de validación como cookie signature not valid y confirma que todas las instancias usan el mismo secreto.
Cuando la cookie que falta es la cookie CSRF que oauth2-proxy establece al iniciar la redirección, el flujo no entra en un bucle. Se detiene en el callback y el registro indica el caso:
No cookies were found in OAuth callback.o, cuando llega alguna otra cookie pero no la correcta:
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF significa falsificación de peticiones entre sitios. Esta cookie permite vincular un callback con el inicio de sesión que lo originó. El navegador muestra una página de error 403 que contiene:
Login Failed: Unable to find a valid CSRF token. Please try again.Las cookies ausentes comparten las tres primeras causas siguientes. La desviación del reloj es otra causa de errores de validación. Comprueba estas cuatro causas en orden.
cookie_secure = truemientras el navegador accedía al sitio mediante HTTP sin cifrar. Excepto en localhost, el navegador no almacena una cookie marcada comoSecureen un origenhttp://, por lo que nunca la vuelve a enviar. Configura correctamente la terminación TLS (seguridad de la capa de transporte) o establececookie_secure = falsesólo durante las pruebas en localhost.- Un valor de
cookie_domainsque no incluye el nombre de host de la barra de direcciones..example.comincluyeapp.example.comy no tiene ningún efecto sobreapp.example.net. - El navegador está descartando la cookie. Una extensión de privacidad estricta o el bloqueo de cookies de terceros puede eliminar
_oauth2_proxy_csrfentre la redirección de salida y el callback, o eliminar después la cookie de sesión. - Desviación del reloj. Si el reloj del servidor está muy adelantado con respecto al del proveedor, el token de ID puede parecer caducado y no superar la validación.
timedatectldebería mostrarSystem clock synchronized: yes.
Hay otra causa que produce el error CSRF sin que exista una configuración incorrecta. De forma predeterminada, oauth2-proxy mantiene una sola cookie CSRF, por lo que dos pestañas que inician sesión al mismo tiempo sobrescriben las cookies de la otra. cookie_csrf_per_request = true asigna una cookie propia a cada inicio de sesión.
Obsérvalo desde el servidor en lugar de hacer suposiciones:
sudo journalctl -u oauth2-proxy -fCarga la aplicación en una ventana privada. Cada petición se registra con su estado, por lo que un callback seguido inmediatamente de otra redirección al inicio de sesión confirma el bucle en el registro.
Rutas que deben omitir el inicio de sesión: API, webhooks y websockets
La autenticación delegada presupone que el navegador tiene una cookie. Las solicitudes sin navegador fallan.
Un cliente de API que envía Authorization: Bearer <token> no tiene ninguna cookie. Por eso, las configuraciones del proxy anteriores lo envían a la página de inicio de sesión de oauth2-proxy, salvo que esté habilitada la autenticación mediante bearer token. Hay dos soluciones claras. Si se configura skip_jwt_bearer_tokens = true, oauth2-proxy acepta un bearer token JWT (JSON web token) válido del emisor configurado, con una audiencia aceptada para este cliente. Esto es adecuado cuando los clientes de la API ya obtienen tokens apropiados del proveedor. El valor aud del token debe coincidir con client_id o con una audiencia configurada mediante extra_jwt_issuers. Como alternativa, excluya la ruta:
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]Cada valor es una expresión regular que se compara con la ruta descodificada sin los parámetros de consulta. También puede llevar delante un método HTTP y =. POST=^/webhook/ deja abierto a POST el receptor del webhook, mientras que una persona que acceda a la misma ruta desde un navegador sigue pasando por el inicio de sesión, siempre que la solicitud de autenticación conserve el método original. Nginx auth_request y Caddy forward_auth realizan comprobaciones GET, por lo que las exclusiones específicas por método requieren un enrutamiento separado en el proxy inverso cuando se usan esas configuraciones. Cada entrada crea un punto sin protección en la barrera de autenticación. Por eso, ancle las expresiones con ^ y manténgalas tan específicas como permita el origen de las solicitudes.
Ejecute v7.15.5 o una versión posterior antes de depender de estas funciones. En versiones anteriores posteriores a v7.5.0, una solicitud con segmentos . o .., una barra inicial duplicada o un punto y coma podía engañar al sistema para que excluyera una ruta protegida (aviso GHSA-63jm-59jj-478j). Anclar las expresiones no impedía este problema. La versión corregida rechaza excluir estas rutas ambiguas. Después de actualizar, compruebe que las rutas públicas sigan coincidiendo.
Los websockets son el caso que más errores genera. La solicitud de actualización es una solicitud HTTP GET normal que lleva las mismas cookies que cualquier otra solicitud. Por tanto, pasa la comprobación normalmente y no necesita ninguna exclusión. El problema está en la configuración del proxy que la rodea. Sin las cabeceras Upgrade y Connection en la ubicación protegida, la actualización no se completa y el cliente de la aplicación vuelve a intentarlo indefinidamente con un mensaje WebSocket connection ... failed en la consola del navegador. Excluir la ruta no soluciona el problema, porque la solicitud ya estaba autorizada.
Sí existe un límite importante. La comprobación se ejecuta una sola vez, durante la actualización. Un websocket que permanece abierto durante horas no se vuelve a comprobar. Por tanto, eliminar a un usuario del proveedor no cierra el socket que ya tiene abierto. Reinicie la aplicación para cerrar las conexiones activas.
Almacenamiento de sesiones y una cookie que crece demasiado
De forma predeterminada, toda la sesión se almacena dentro de la cookie y se cifra con su cookie_secret. Esto permite que oauth2-proxy no mantenga estado y evita necesitar otro servicio. También tiene un límite, porque los navegadores limitan las cookies a unos 4 KB. Cuando el token de identidad contiene una lista larga de notificaciones de grupo, oauth2-proxy divide la sesión entre _oauth2_proxy_0, _oauth2_proxy_1 y las siguientes cookies. Si se superan unas pocas partes, las cabeceras de la solicitud crecen lo suficiente para que nginx responda con 400 Request Header Or Cookie Too Large antes de que la aplicación reciba la solicitud.
Cuando ocurra esto, mueva la sesión al servidor:
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"El navegador conserva entonces un ticket corto y la sesión cifrada se almacena en Redis. El coste es que debe mantenerse activo otro servicio: si Redis deja de funcionar, oauth2-proxy no puede cargar las sesiones; si se pierden los datos de sesión almacenados, todos deben iniciar sesión de nuevo. El almacenamiento en cookies también tiene un coste: dos solicitudes que actualizan la misma sesión al mismo tiempo pueden entrar en conflicto y obligar a iniciar sesión de nuevo.
Qué no proporciona forward auth
Esto es una barrera de acceso. No es autorización dentro de la aplicación. Esa diferencia determina si este enfoque se ajusta a su caso.
Una vez que el usuario supera la barrera, la aplicación ve lo mismo que veía antes. Si la aplicación tiene sus propios roles, forward auth no los asigna, a menos que la aplicación admita autenticación basada en cabeceras y asocie una cabecera con una cuenta. Grafana lo permite mediante sus opciones auth.proxy. La mayoría de las aplicaciones autoalojadas no lo permiten. Por tanto, todos los usuarios que superan la barrera tienen la misma identidad para la aplicación. Esa identidad suele ser una cuenta de administrador.
Tampoco protege los tokens de API propios de la aplicación. Un token de acceso personal emitido por la aplicación autentica al usuario en la aplicación, no en oauth2-proxy. Por eso, el token deja de funcionar en cuanto la barrera se coloca delante de la aplicación. Si excluye la ruta de la API para recuperarlo, ese token se convierte en el único mecanismo que protege la ruta. Ahora tiene dos sistemas de autenticación para un mismo servicio, y SSO cubre sólo uno de ellos.
La revocación es la tercera limitación. Eliminar un usuario del proveedor impide nuevos inicios de sesión, pero oauth2-proxy no comprueba una sesión existente con el proveedor hasta que vence cookie_refresh. Con la renovación desactivada, la cookie de sesión sigue siendo válida hasta que caduca, y cookie_expire tiene un valor predeterminado de 168 hours. Eso puede proporcionar una semana de acceso a alguien que acaba de eliminar. Establezca cookie_refresh en un valor corto, como una hora. Cuando el proveedor rechace esa renovación porque el token de renovación del usuario ya no sea válido, oauth2-proxy eliminará la sesión y forzará un nuevo inicio de sesión en la siguiente solicitud que intente renovarla. No todos los proveedores admiten la renovación. Pruébela con su proveedor.
El registro de auditoría también termina en la barrera. oauth2-proxy registra quién la atravesó y cuándo. La aplicación registra una sesión sin nombre. Si tiene que responder quién cambió una configuración, la identidad mediante cabeceras en la aplicación es el mínimo necesario. Las cuentas reales por usuario son la respuesta correcta.
Cuándo pagar por SSO es la mejor opción
La autenticación delegada es la opción adecuada cuando una aplicación no tiene inicio de sesión o usa una sola contraseña compartida, y quiere disponer de un único lugar para añadir y eliminar usuarios. Configurarla cuesta una tarde y añade un proceso, pero funciona con cualquier aplicación que use HTTP.
Es la opción incorrecta cuando distintas personas necesitan permisos diferentes dentro de la misma aplicación. Una puerta de acceso no puede expresar que «Ana puede editar los paneles y Bo sólo puede leerlos». Si el proveedor ofrece un nivel con SSO, la asignación de grupos a roles suele ser precisamente lo que está comprando. Reproducirla con cabeceras y reglas del proxy es más frágil que pagar por ella. Conviene leer El patrón de precios de esos niveles con SSO antes de decidir.
Cualquier aplicación con un cliente móvil o de escritorio que no conserve las cookies del navegador tendrá problemas con la puerta de acceso en cada petición.
FAQ
¿Qué es la autenticación delegada?
La autenticación delegada es un patrón en el que el proxy inverso consulta a un servicio de autenticación independiente para cada solicitud entrante antes de enviarla al upstream. El proxy envía las cabeceras de la solicitud a un endpoint como /oauth2/auth y lee el código de estado. 202 significa que la solicitud está permitida, por lo que la solicitud original se envía a la aplicación. 401 significa que no existe una sesión válida, por lo que el proxy redirige el navegador al inicio de sesión. Nginx lo implementa con la directiva auth_request, Traefik con el middleware forwardAuth y Caddy con forward_auth.
¿Por qué oauth2-proxy me redirige a la página de inicio de sesión en un bucle?
Falta la cookie de sesión o no supera la validación. Por eso, cada comprobación no encuentra una sesión válida y vuelve a enviarlo al inicio de sesión. Las instancias que usan secretos de cookie diferentes rechazan las cookies de las demás. Otra causa es cookie_secure = true en un sitio al que el navegador accedió mediante HTTP sin cifrar, porque, salvo en localhost, un navegador no almacena una cookie Secure en un origen http://. Compruebe también si el valor de cookie_domains no incluye el nombre de host que aparece en la barra de direcciones. Lea la cabecera Set-Cookie en la respuesta /oauth2/callback desde las herramientas de desarrollo del navegador para ver qué cookie falta. Si la cookie se devuelve, revise el registro del servidor en busca de errores de validación. Si falta la cookie CSRF, aparece una página 403 con el texto Login Failed: Unable to find a valid CSRF token. Please try again. en lugar de un bucle, y el registro muestra No cookies were found in OAuth callback. cuando no llegó ninguna cookie.
¿Cómo permito el acceso de un cliente API o un webhook a través de oauth2-proxy?
Use skip_auth_routes con una expresión regular anclada, opcionalmente limitada a un método HTTP, por ejemplo POST=^/webhook/, y ejecute v7.15.5 o una versión posterior. Esa versión corrige una omisión crítica de estas excepciones. Las excepciones específicas por método requieren que la solicitud de autenticación conserve el método original. Los ejemplos de nginx y Caddy realizan comprobaciones GET, por lo que debe gestionar esas excepciones en el enrutamiento del proxy inverso. Si sus clientes API ya tienen JWT válidos emitidos por el proveedor configurado y con una audiencia aceptada, skip_jwt_bearer_tokens = true acepta esos tokens en lugar de una cookie y mantiene la ruta protegida. La audiencia debe coincidir con client_id o con una audiencia configurada mediante extra_jwt_issuers. Todo lo incluido en skip_auth_routes queda sin autenticación para todos los usuarios, por lo que cada expresión debe ser tan restrictiva como permita el cliente.
¿oauth2-proxy proporciona permisos por usuario a la aplicación?
No. Es una barrera de acceso, no un sistema de autorización. Decide quién llega a la aplicación. Todas las personas que llegan a ella son idénticas para la aplicación, salvo que esta lea las cabeceras de identidad y las asocie a cuentas. Grafana puede hacerlo mediante la configuración auth.proxy. La mayoría de las aplicaciones autoalojadas no pueden hacerlo, por lo que todas las personas que superan la barrera comparten la identidad única con la que se ejecuta la aplicación.
¿Alguien puede omitir oauth2-proxy estableciendo por su cuenta la cabecera de identidad?
Sí, si puede acceder directamente a la aplicación. La identidad llega como una cabecera sin cifrar, como X-Auth-Request-Email, y la aplicación confía en cualquier valor que reciba. Cualquiera que pueda abrir una conexión al puerto de la aplicación puede enviar esa cabecera y hacerse pasar por cualquier usuario. Enlace la aplicación a 127.0.0.1 o manténgala en una red Docker interna sin ningún puerto publicado, y confírmelo con sudo ss -tlnp.