Implementación de Autenticación Centralizada en Nginx con OAuth2 Proxy y Keycloak

🚀 Introducción a la Autenticación Centralizada con Nginx

En el panorama actual del desarrollo de software y la administración de sistemas, proteger múltiples aplicaciones individuales con sus propias bases de datos de usuarios es ineficiente y peligroso. La solución moderna es adoptar una arquitectura de Autenticación Centralizada. Al combinar el rendimiento de Nginx como proxy inverso con la potencia de Keycloak como proveedor de identidad (IdP) y OAuth2 Proxy como intermediario, podemos asegurar cualquier servicio web de forma unificada sin modificar el código de la aplicación original.

Intermedio DevOps & Seguridad

"Centralizar la identidad reduce la superficie de ataque, simplifica la gestión de usuarios y permite implementar características avanzadas como el inicio de sesión único (SSO) y la autenticación multifactor (MFA) de manera transparente."

📋 Requisitos Previos y Arquitectura

Antes de sumergirnos en la configuración, asegúrate de contar con los siguientes elementos en tu entorno de pruebas o producción:

• Un servidor con Nginx instalado y funcionando.
• Una instancia de Keycloak accesible por red (puede ser local o en la nube).
• Una aplicación de backend de ejemplo (por ejemplo, un servicio web básico en el puerto 8080).
• Docker y Docker Compose (recomendado para desplegar OAuth2 Proxy de forma rápida).

⏱️ Tiempo estimado de implementación

🛠️ Paso 1: Configuración del Cliente en Keycloak

El primer paso consiste en registrar nuestra aplicación dentro del servidor de identidad Keycloak para que este reconozca las solicitudes provenientes de OAuth2 Proxy.

1. Accede a la consola de administración de Keycloak.
2. Selecciona tu Realm (o crea uno nuevo, por ejemplo, empresa-realm).
3. En el menú lateral, navega a Clients y haz clic en Create client.
4. Configura los siguientes parámetros básicos:
   • Client type: OpenID Connect
   • Client ID: nginx-oauth2-client
   • Name: Nginx OAuth2 Proxy Client
5. Haz clic en Next y asegúrate de habilitar Client authentication (esto generará un Client Secret secreto).
6. En la sección de URLs de validación, configura:
   • Root URL: https://tu-dominio.com
   • Home URL: https://tu-dominio.com
   • Valid redirect URIs: https://tu-dominio.com/oauth2/callback
7. Guarda los cambios.

⚙️ Paso 2: Despliegue y Configuración de OAuth2 Proxy

OAuth2 Proxy actúa como un servicio intermediario que intercepta las peticiones HTTP y valida si el usuario posee una cookie de sesión válida. Si no es así, redirige automáticamente al usuario hacia Keycloak.

Crearemos un archivo de configuración para OAuth2 Proxy llamado oauth2-proxy.cfg:

provider = "keycloak-oidc"
provider_display_name = "Keycloak"
client_id = "nginx-oauth2-client"
client_secret = "TU_CLIENT_SECRET_GENERADO_EN_KEYCLOAK"
login_url = "https://keycloak.tu-dominio.com/realms/empresa-realm/protocol/openid-connect/auth"
redeem_url = "https://keycloak.tu-dominio.com/realms/empresa-realm/protocol/openid-connect/token"
validate_url = "https://keycloak.tu-dominio.com/realms/empresa-realm/protocol/openid-connect/userinfo"
cookie_secret = "COMPRUEBA_GENERAR_UN_SECRETO_ALEATORIO_DE_32_BYTES"
email_domains = ["*"]
upstream = "http://127.0.0.1:8080"
http_address = "127.0.0.1:4180"
cookie_secure = true

🌐 Paso 3: Configuración Avanzada de Nginx

Ahora configuraremos Nginx para que gestione las solicitudes públicas, redirija las peticiones no autenticadas a OAuth2 Proxy e inyecte las cabeceras necesarias hacia nuestra aplicación de backend.

Crea o modifica el archivo de configuración de tu sitio en Nginx (por ejemplo, /etc/nginx/sites-available/app-protegida):

server {
    listen 80;
    server_name tu-dominio.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name tu-dominio.com;

    ssl_certificate /etc/letsencrypt/live/tu-dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tu-dominio.com/privkey.pem;

    # Ruta de inicio de sesión gestionada por OAuth2 Proxy
    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-Scheme $scheme;
        proxy_set_header X-Auth-Request-Redirect $request_uri;
    }

    # Endpoint interno para la validación de subrequest de Nginx
    location = /oauth2/auth {
        internal;
        proxy_pass http://127.0.0.1:4180/oauth2/auth;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header Content-Length "";
        proxy_pass_body "";
    }

    # Protección de la aplicación principal
    location / {
        auth_request /oauth2/auth;
        auth_request_set $user $upstream_http_x_auth_request_user;
        auth_request_set $email $upstream_http_x_auth_request_email;
        auth_request_set $token $upstream_http_x_auth_request_access_token;
        
        proxy_set_header X-User $user;
        proxy_set_header X-Email $email;
        proxy_set_header Authorization "Bearer $token";

        error_page 401 = /oauth2/start?rd=$request_uri;

        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🔍 Paso 4: Verificación y Pruebas del Sistema

Una vez aplicadas las configuraciones, es momento de validar que todo funcione correctamente.

1. Verifica la sintaxis de Nginx:

sudo nginx -t

2. Recarga el servicio de Nginx para aplicar los cambios:

sudo systemctl reload nginx

3. Abre tu navegador web e intenta ingresar a https://tu-dominio.com.
4. Deberías ser redirigido automáticamente a la pantalla de inicio de sesión de Keycloak.
5. Ingresa tus credenciales corporativas o de usuario de prueba.
6. Una vez autenticado con éxito, Keycloak te redirigirá de vuelta a Nginx, el cual validará tu token a través de OAuth2 Proxy y te permitirá acceder finalmente a tu aplicación backend en el puerto 8080.

❓ Preguntas Frecuentes (FAQ)

🎯 Conclusión

Has implementado con éxito un sistema de autenticación centralizado y robusto utilizando Nginx, OAuth2 Proxy y Keycloak. Esta arquitectura protege tus aplicaciones heredadas o modernas sin requerir cambios en su código fuente, aportando una capa de seguridad empresarial estandarizada bajo protocolos modernos como OpenID Connect.