Guía para usar Auth Proxy en Grafana con OAuth2-Proxy e IdP Keycloak

Fecha publicación
Dificultad
Avanzado
#
12
3 more properties
Publicado
tags
IoT, Gateways, logs, métricas, plataforma, Grafana, Alloy, Docker, sistema, Mimir, Loki, MinIO, almacenamiento, AWS, S3, visualización, monitoreo, captura, servidores, integración, DB, BBDD, servers, integration, metrics, systems, logs, keycloak, oauth2, oauth2-client-credentials, OAuth2-Proxy, Identity Provider
vídeo local


Descripción

Se describe el proceso de delegar la autenticación en un reverse proxy (gestionado por NPM) que utiliza OAuth2‑Proxy para gestionar las cookies de sesión y redirecciones, mientras Keycloak se encarga de la autenticación y la provisión de información del usuario en las cabeceras HTTP. Este enfoque no solo simplifica la arquitectura de la aplicación, sino que también ofrece una mayor seguridad y una administración centralizada de las identidades, permitiendo que Grafana (y cualquier otra aplicación) se integre de forma transparente en un ecosistema IAM robusto y escalable.

Funcionalidad de los actores

Grafana y la función Auth Proxy

Grafana permite configurar un reverse proxy HTTP para que se encargue de la autenticación. Con la funcionalidad de Auth Proxy, Grafana confía en el proxy para autenticar a los usuarios. Esto significa que, en lugar de gestionar directamente el proceso de autenticación (login, logout, validación de tokens, etc.), Grafana espera que el proxy le entregue, mediante cabeceras HTTP, la información necesaria del usuario autenticado.

Rol del Nginx Proxy Manager (NPM)

El Nginx Proxy Manager actúa como el encargado de gestionar las configuraciones del proxy Nginx de forma centralizada y sencilla. En este escenario, NPM se sitúa en el frente del sistema y se encarga de:

Papel de Keycloak en la Gestión de Identidades

Keycloak es una solución de gestión de identidades y acceso (IAM) que proporciona mecanismos robustos de autenticación mediante el estándar OpenID Connect. En este contexto, Keycloak:

Gestión de Sesiones y Redirecciones con OAuth2‑Proxy

OAuth2‑Proxy se sitúa como cliente de Keycloak en este modelo. Su función principal es:
De esta forma, OAuth2‑Proxy actúa como puente entre Keycloak y Grafana, aliviando al NPM de la necesidad de gestionar mecanismos complejos de autenticación.

Ventajas del modelo propuesto

Secuencia del proceso

A continuación se describe, paso a paso, el proceso interno (según el diagrama "Grafana: OAuth2 Authorization Code with HTTP proxy") que permite que un usuario acceda a Grafana sin que éste tenga que implementar su propia lógica de autenticación, heredando la sesión a través del proxy:
OAuth2-Grafana OAuth2 Authorization Code with HTTP proxy.drawio.svg

  1. Acceso Inicial: El usuario intenta acceder a Grafana a través de su navegador. No existe una sesión activa.
  2. Detección de Ausencia de Sesión: Grafana (o el componente que actúa como puerta de entrada) detecta que no hay un token o cookie de sesión y, por tanto, no conoce la identidad del usuario.
  3. Redirección al Proxy de Autenticación: La solicitud se redirige automáticamente al componente de autenticación, que en este caso es OAuth2‑Proxy, configurado para trabajar detrás de un reverse proxy (como Nginx Proxy Manager).
  4. Inicio del Flujo OAuth2: OAuth2‑Proxy genera una solicitud de autorización y redirige al usuario a la URL de autorización de Keycloak, incluyendo parámetros esenciales como el client_id, scope y la URL de redirección.
  5. Redirección a Keycloak: El navegador del usuario sigue la redirección y llega a la pantalla de login de Keycloak.
  6. Presentación de la Pantalla de Login: Keycloak muestra al usuario el formulario de autenticación.
  7. Ingreso de Credenciales: El usuario introduce sus credenciales (usuario y contraseña, o utiliza otro mecanismo de autenticación configurado).
  8. Validación de Credenciales en Keycloak: Keycloak valida las credenciales; si son correctas, autentica al usuario.
  9. Emisión del Código de Autorización: Tras la autenticación, Keycloak genera un código de autorización temporal y redirige al navegador del usuario hacia la URL de redirección definida (controlada por OAuth2‑Proxy).
  10. Recepción del Código en OAuth2‑Proxy: El navegador envía la solicitud de vuelta a OAuth2‑Proxy, incluyendo el código de autorización en la URL.
  11. Intercambio del Código por un Token: OAuth2‑Proxy utiliza el código de autorización para realizar una solicitud al endpoint de tokens de Keycloak, enviando además el client_id y client_secret.
  12. Verificación del Código y Emisión de Token: Keycloak verifica el código y, de ser correcto, devuelve un token de acceso (y, opcionalmente, un token de refresco).
  13. Validación del Token: OAuth2‑Proxy recibe y valida el token emitido por Keycloak para asegurarse de su integridad y vigencia.
  14. Creación de la Sesión en OAuth2‑Proxy: Con el token validado, OAuth2‑Proxy crea (o actualiza) la sesión del usuario internamente y asocia la información obtenida (como el correo, nombre, roles, etc.).
  15. Establecimiento de la Cookie de Sesión: OAuth2‑Proxy establece una cookie de sesión en el navegador, que servirá para identificar al usuario en solicitudes posteriores sin necesidad de repetir el flujo.
  16. Inyección de Cabeceras de Autenticación: Además, OAuth2‑Proxy añade cabeceras HTTP (por ejemplo, X-Auth-Request-Email, X-Auth-Request-Preferred-Username, etc.) que contienen los datos relevantes del usuario autenticado.
  17. Redirección Final a Grafana: Una vez configurada la sesión, OAuth2‑Proxy redirige al usuario de vuelta a Grafana, incluyendo la información de autenticación a través de las cabeceras.
  18. Recepción de la Solicitud Autenticada en Grafana: Grafana recibe la solicitud ya “preautenticada” gracias a las cabeceras inyectadas.
  19. Confianza en la Sesión Heredada: Grafana confía en la información proporcionada por el proxy (ya que se asume que el reverse proxy es seguro) y utiliza esos datos para identificar al usuario sin necesidad de realizar un proceso de login interno.
  20. Creación de la Sesión Interna en Grafana: Con la información heredada, Grafana establece su propia sesión interna (por ejemplo, asociando la solicitud a un usuario concreto en su sistema) y permite el acceso.
  21. Acceso al Sistema: El usuario ya autenticado accede a Grafana y puede utilizar todas las funcionalidades sin que Grafana haya tenido que gestionar la autenticación directamente.
  22. Mantenimiento de la Sesión en Solicitudes Futuras: Las solicitudes posteriores incluyen la cookie de sesión establecida, lo que permite que Grafana valide la sesión sin necesidad de repetir todo el proceso, manteniendo así la experiencia de usuario sin interrupciones.

Configuraciones

Nginx Proxy Manager

Capturas de la configuración:
image.png
image.png
image.png
image.png

Configuración de OAuth2 Proxy

docker-compose.yaml

YAML
name: oauth_proxy_i40sys

x-logging:
  &default-logging
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "1"

services:
  redis:
    image: redis:alpine
    # container_name: redis
    networks:
      - private
    volumes:
      - /docker-data/oauth2-proxy.i40sys/redis:/data  # Optional: for data persistence
    logging: *default-logging
    
  proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.7.1
    command: --config=/oauth2-proxy.cfg --code-challenge-method=S256
    environment:
      - OAUTH2_PROXY_COOKIE_SECRET=LJAxLJAxLJAxLJAxLJAxMQ==
      - OAUTH2_PROXY_BACKEND_LOGOUT_URL=https://iam.i40sys.com/realms/observability/protocol/openid-connect/logout?id_token_hint={id_token}
    networks:
      - private
      - proxy-network
    volumes:
      - /docker-data/oauth2-proxy.i40sys/config/oauth2-proxy.cfg:/oauth2-proxy.cfg
    depends_on:
      - redis
    logging: *default-logging
networks:
  private:
  proxy-network:
    name: services
    external: true

config/oauth2-proxy.cfg

Bash
## OAuth2 Proxy Config File
## https://github.com/oauth2-proxy/oauth2-proxy

http_address="0.0.0.0:4180"
reverse_proxy = true
redirect_url="https://proxy.i40sys.com/oauth2/callback"

standard_logging = true
standard_logging_format = "[{{.Timestamp}}] [{{.File}}] {{.Message}}"
request_logging = true
request_logging_format = "{{.Client}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}}"
auth_logging = true
auth_logging_format = "{{.Client}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}"

pass_user_headers = true
email_domains = "*"

client_id = "oauth2_proxy"
client_secret = "kxRSwAqJqcxoB4GJ7LaeUJ9n3ymJBljh"

pass_access_token = true
cookie_name = "oauth2_proxy_i40sys"
# cookie_secret = ""
cookie_domains = ".i40sys.com"
# cookie_expire = "168h"
cookie_refresh = "5m"
cookie_secure = true
cookie_httponly = false

whitelist_domains = [
    "iam.i40sys.com:*",
    "*.i40sys.com:*",
    "*:*"
]

oidc_issuer_url = "https://iam.i40sys.com/realms/observability"
provider = "oidc"
provider_display_name = "Keycloak"
skip_provider_button = "true"
set_authorization_header = true
set_xauthrequest =  true

cookie_csrf_per_request=true
cookie_csrf_expire="5m"
cookie_samesite="lax"

session_store_type="redis"
redis_connection_url="redis://redis:6379"

show_debug_on_error=true

Configuración de Grafana

Toda la configuración de esta prueba de concepto esta dentro del fichero compose de docker: (docker-compose.yaml)
YAML
name: grafana_i40sys

x-logging:
  &default-logging
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "1"

services:
  grafana:
    image: grafana/grafana:latest
    restart: unless-stopped
    environment:
      - GF_LOG_LEVEL=debug
      - GF_SERVER_ROOT_URL=https://grafana.i40sys.com/
      - GF_DATAPROXY_SEND_USER_HEADER=true
      - GF_SECURITY_ADMIN_USER=oriol@joor.net
      - GF_AUTH_DISABLE_LOGIN_FORM=true
      - GF_AUTH_SIGNOUT_REDIRECT_URL=https://grafana.i40sys.com/oauth2/sign_out?rd=https://grafana.i40sys.com
      - GF_AUTH_ANONYMOUS_ENABLED=false
      - GF_USERS_ALLOW_SIGN_UP=false
      - GF_USERS_AUTO_ASSIGN_ORG=true
      - GF_USERS_AUTO_ASSIGN_ORG_ID=1
      - GF_USERS_AUTO_ASSIGN_ORG_ROLE=Editor
      - GF_AUTH_PROXY_ENABLED=true
      - GF_AUTH_PROXY_HEADER_NAME=X-Email
      - GF_AUTH_PROXY_HEADER_PROPERTY=email
      - GF_AUTH_PROXY_AUTO_LOGIN=true
      - GF_AUTH_PROXY_HEADERS="Name:X-Username Groups:X-Groups"
    volumes:
      - /etc/localtime:/etc/localtime:ro
    networks:
      - services
    logging: *default-logging

networks:
  services:
    external: true
    name: services

Referencias