Skip to main content

OAuth2-Proxy

OAuth2 Proxy

OAuth2-Proxy es un servicio que actúa como puerta de entrada: delega la autenticación en un IdP (OIDC/OAuth2 como Entra ID) y, si el login es válido, inyecta cabeceras (email, nombre, grupos, token) hacia tus apps, evitando tener que modificar cada servicio. Con Traefik se usa mediante ForwardAuth; con Nginx/NPM, mediante auth_request al endpoint /auth de OAuth2-Proxy.

image.png

Enlaces

https://github.com/oauth2-proxy/oauth2-proxy/blob/master/README.md

Requisitos

Entra ID (Azure AD) + OAuth2-Proxy (OIDC)

Registro App

Cómo registrar una aplicación en Entra ID de Microsoft - Microsoft identity platform | Microsoft Learn

Desde la consola de Microsoft Entra Admin Center (https://entra.microsoft.com), registra una nueva aplicación con un nombre descriptivo "OAuth-Proxy" y asegúrate de que la opción single tenant esté seleccionada. Establece Redirect URI para que apunte a https://auth.dominio.com/oauth2/callback

image.png

Secreto de cliente

https://learn.microsoft.com/es-es/entra/identity-platform/how-to-add-credentials?tabs=client-secret

Desde la consola de Microsoft Entra Admin Center (https://entra.microsoft.com), en Registros de aplicaciones, seleccione la aplicación creada anteriormente "OAuth-Proxy", seleccione Certificados y secretos>Secretos de cliente>Nuevo secreto de cliente:

  1. Agregue una descripción para la clave secreta de cliente.

  2. Seleccione una expiración para el secreto o especifique una duración personalizada.

  3. Registre el valor del secreto de cliente para usarlo en el código de la aplicación cliente. Este valor secreto nunca se muestra de nuevo después de salir de esta página.

image.png

Credenciales necesarias (del App Registration en Entra ID):

  • Client ID

  • Client Secret

  • Tenant ID

  • Redirect URL: https://<tu-dominio>/oauth2/callback

Portainer

Add a new stack – Portainer Documentation

Web editor

En Portainer «Stack» agregamos nuevo usando el editor WEB pegando el contenido del fichero «docker-compose.yml» y el contenido del fichero de variables2.15-docker_add_stack_web_editor.gif

Fichero de variables

TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_SECRET=xxxxx~xxxxxxxxxxxxxxxxxxxxxxxxxx
COOKIE_SECRET=generating-a-cookie-secret

Fichero docker-compose

services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:latest
    container_name: oauth2-proxy
    command:
      - --http-address=0.0.0.0:4180
    restart: unless-stopped
    env_file: stack.env
    environment:
      OAUTH2_PROXY_PROVIDER: "oidc"
      OAUTH2_PROXY_OIDC_ISSUER_URL: "https://login.microsoftonline.com/${TENANT_ID}/v2.0"
      OAUTH2_PROXY_CLIENT_ID: "${CLIENT_ID}"
      OAUTH2_PROXY_CLIENT_SECRET: "${CLIENT_SECRET}"
      OAUTH2_PROXY_REDIRECT_URL: "https://auth.dominio.com/oauth2/callback"
      OAUTH2_PROXY_WHITELIST_DOMAINS: ".dominio.com"
      OAUTH2_PROXY_EMAIL_DOMAINS: "*"
      OAUTH2_PROXY_COOKIE_SECRET: "${COOKIE_SECRET}"
      OAUTH2_PROXY_COOKIE_SECURE: "true"
      OAUTH2_PROXY_COOKIE_SAMESITE: "lax"
      OAUTH2_PROXY_SET_XAUTHREQUEST: "true"         # útil para Nginx/NPM
      OAUTH2_PROXY_PASS_ACCESS_TOKEN: "true"        # útil si el upstream necesita bearer
      OAUTH2_PROXY_PASS_AUTHORIZATION_HEADER: "true"
      OAUTH2_PROXY_REVERSE_PROXY: "true"
      OAUTH2_PROXY_UPSTREAMS: "file:///dev/null"    # modo “auth-gateway” sin proxy a app
    labels:
      - traefik.enable=true
      - traefik.http.routers.oauth2-proxy.rule=Host(`auth.dominio.com`)
      - traefik.http.routers.oauth2-proxy.tls=true
      - traefik.http.routers.oauth2-proxy.tls.certresolver=letsencrypt
      - traefik.http.routers.oauth2-proxy.service=oauth2-proxy
      - traefik.http.services.oauth2-proxy.loadbalancer.server.port=4180
      - traefik.http.services.oauth2-proxy.loadbalancer.server.scheme=http
      # Middleware de ForwardAuth -> oauth2-proxymiddleware
      - traefik.http.middlewares.oauth2proxy.forwardauth.address=http://oauth2-proxy:4180/oauth2/auth
      - traefik.http.middlewares.oauth2proxy.forwardauth.trustForwardHeader=true
      - traefik.http.middlewares.oauth2proxy.forwardauth.authResponseHeaders=Authorization,X-Auth-Request-User,X-Auth-Request-Email,X-Auth-Request-User,AuthorizationPreferred-Username
      # Middleware quede captura 401-403 y reenvía a /oauth2/start del propio oauth2-proxyerrores
      - traefik.http.middlewares.oauth-errors.errors.status=401-403
      - traefik.http.middlewares.oauth-errors.errors.service=oauth2-proxy
      - traefik.http.middlewares.oauth-errors.errors.query=/oauth2/start?sign_in?rd={url}
    networks:
      - proxy

networks:
  proxy:
    external: true

Con Entra ID usa el proveedor OIDC. El issuer suele ser: https://login.microsoftonline.com/<TENANT_ID>/v2.0, y los scopes típicos: openid profile email. 

En este punto ya puedes ir a https://auth.dominio.com/oauth2/sign_in y probar la validación

Integración con Traefik (ForwardAuth)

traefik-concepts-1.webp

Traefik delega la auth a OAuth2-Proxy; si /auth devuelve 2xx, pasa la request. Un middleware ForwardAuth apuntando a http://oauth2-proxy:4180/auth reenvía cabeceras útiles (p. ej., X-Auth-Request-Email).

Añadiendo a la aplicaciones que queramos validar la etiqueta: traefik.http.routers.app.middlewares=oauth2proxy@docker

Labels

    labels:
      - traefik.http.routers.app.middlewares=oauth2proxy@docker

cambia en la etiqueta "app" por el valor nombre de tu aplicación

Back to top