Saltar al contenido principal

OAuth2 Proxy

OAuth2 Proxy es un proxy inverso que inicia sesión a los usuarios con un proveedor OIDC antes de que lleguen a tu aplicación. También puede actuar como endpoint de forward-auth para Nginx, Caddy o Traefik. Con Casdoor como proveedor, puedes permitir el acceso solo a los miembros de un grupo de Casdoor o a los usuarios que poseen un rol de Casdoor.

La configuración en esta página fue probada de extremo a extremo con OAuth2 Proxy v7.15 y Casdoor v4.17.

consejo

Si solo necesitas el inicio de sesión de Casdoor delante de una aplicación y no necesitas OAuth2 Proxy en sí, casdoor-forward-auth hace el mismo trabajo para Traefik, Caddy y Nginx, y pasa los grupos y roles del usuario en las cabeceras de la solicitud.

Paso 1: Crear la aplicación en Casdoor​

  1. En la organización de tus usuarios, añade una aplicación (o abre una existente).

  2. Añade el callback de OAuth2 Proxy a Redirect URLs:

    https://app.example.com/oauth2/callback
  3. En la pestaña OIDC/OAuth, establece:

    • Token format: JWT-Standard
    • Token group format: Name (group), para que los grupos lleguen como devs en lugar de my-org/devs
  4. Guarda y anota el Client ID y el Client secret.

Por qué JWT-Standard: con el formato predeterminado JWT, un usuario cuyo correo electrónico no está verificado no puede iniciar sesión (OAuth2 Proxy rechaza email_verified: false, y los usuarios creados por un administrador suelen tener un correo no verificado), y la reclamación roles contiene objetos de rol completos en lugar de nombres de rol. Consulta Qué envía Casdoor.

Paso 2: Configurar OAuth2 Proxy​

Crea oauth2-proxy.cfg:

provider = "oidc"
oidc_issuer_url = "https://door.example.com"
client_id = "<client ID>"
client_secret = "<client secret>"
redirect_url = "https://app.example.com/oauth2/callback"
scope = "openid email profile"
email_domains = ["*"]

cookie_secret = "<random secret>"
http_address = "0.0.0.0:4180"
upstreams = ["http://127.0.0.1:8080"]

# Let in only members of the Casdoor group "devs"
oidc_groups_claim = "groups"
allowed_groups = ["devs"]
  • oidc_issuer_url es la URL de Casdoor, sin barra final. Debe ser exactamente el issuer mostrado en https://door.example.com/.well-known/openid-configuration. Casdoor construye el emisor desde origin en conf/app.conf, o desde el host de la solicitud cuando origin está vacío; si ambos difieren, OAuth2 Proxy fallará con issuer did not match.
  • cookie_secret debe tener 16, 24 o 32 bytes, por ejemplo la salida de openssl rand -base64 32 | tr -- '+/' '-_'.
  • Mantén el ámbito profile: Casdoor devuelve grupos y roles desde su endpoint userinfo solo cuando se otorga profile.
  • upstreams es tu aplicación.

Inícialo:

oauth2-proxy --config oauth2-proxy.cfg

Abre https://app.example.com. Después de iniciar sesión en Casdoor, los miembros de devs acceden a la aplicación y todos los demás reciben 403 Forbidden.

Restringir el acceso por rol en su lugar​

Para comprobar un rol de Casdoor en lugar de un grupo, lee la reclamación roles:

oidc_groups_claim = "roles"
allowed_groups = ["admin"]

allowed_groups contendrá entonces nombres de rol, sin la organización.

Comprobar lo que recibió OAuth2 Proxy​

Después de iniciar sesión, abre https://app.example.com/oauth2/userinfo. Muestra los grupos que extrajo OAuth2 Proxy:

{"user":"d1a5f427-...","email":"alice@example.com","groups":["devs"],"preferredUsername":"alice"}

Si groups está vacío, el usuario no tiene ningún grupo o rol en Casdoor, o el nombre de la reclamación es incorrecto. Si contiene cadenas JSON largas como {"owner":"my-org","name":"admin",...}, la aplicación todavía usa el formato predeterminado JWT con oidc_groups_claim = "roles"; cambia el formato a JWT-Standard.

Qué envía Casdoor​

Cómo llegan los grupos y roles del usuario a OAuth2 Proxy depende del Token format de la aplicación:

Token formatgroupsrolesUnverified email
JWT-Standardfrom userinfo, group namesfrom userinfo, role namessigns in
JWT-Customin the token if Groups is in Token fieldsin the token if you add a token attribute roles (see below)signs in
JWT (default)in the tokenrole objects, not usable for allowed_groupsrejected
JWT-Emptyin the tokenfrom userinfo, role namessigns in

Con JWT-Standard, el token en sí solo lleva reclamaciones OIDC estándar. OAuth2 Proxy busca cualquier reclamación que falte en el token en el endpoint userinfo de Casdoor, por lo que groups y roles llegan igualmente, una vez por inicio de sesión.

Token group format controla los valores de grupo en todos los formatos: ID (predeterminado) da my-org/devs, Name da devs, y Path da my-org/parent/devs para grupos anidados.

Para poner los nombres de rol en el token en sí, usa JWT-Custom y agrega una fila a Token attributes:

NameCategoryValueType
rolesExisting FieldRolesArray

Si Token fields no está vacío, también limita lo que devuelve el endpoint userinfo (ver Token fields). Incluye Groups (y Roles cuando lees roles desde userinfo), o déjalo vacío.

Si debes mantener el formato predeterminado JWT, agrega insecure_oidc_allow_unverified_email = true para que los usuarios con correo no verificado puedan iniciar sesión, y restringe solo por groups.

Pasar el usuario a tu aplicación​

OAuth2 Proxy agrega estos encabezados a las solicitudes que reenvía (pass_user_headers, activado por defecto):

HeaderValue
X-Forwarded-UserCasdoor user ID (the sub claim)
X-Forwarded-Preferred-UsernameNombre de usuario de Casdoor, p. ej. alice
X-Forwarded-EmailEmail address
X-Forwarded-GroupsGroups (or roles), comma separated

Asegúrate de que tu aplicación solo sea accesible a través de OAuth2 Proxy; de lo contrario, cualquiera puede enviar estos encabezados directamente.

Para usar OAuth2 Proxy como endpoint de autenticación anticipada (forward-auth) de Nginx (auth_request), Caddy (forward_auth) o Traefik (forwardAuth) en lugar de como proxy inverso, apunta el proxy a su endpoint /oauth2/auth; consulta Integrations en la documentación de OAuth2 Proxy.

Solución de problemas​

SymptomCause and fix
issuer did not match the issuer returned by provider at startupoidc_issuer_url differs from the issuer in Casdoor's discovery document. Set origin in Casdoor's conf/app.conf to its public URL and use the same value here.
500 after sign-in, log says email in id_token ... isn't verifiedThe application uses the default JWT format and the user's email is not verified. Switch to JWT-Standard, or set insecure_oidc_allow_unverified_email = true.
403 Forbidden after sign-inThe user is not in allowed_groups. Open /oauth2/userinfo to see what OAuth2 Proxy received and compare it with Token group format.
Casdoor shows Redirect URI: ... doesn't exist in the allowed Redirect URI listAdd https://app.example.com/oauth2/callback to the application's Redirect URLs.