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.
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
-
En la organización de tus usuarios, añade una aplicación (o abre una existente).
-
Añade el callback de OAuth2 Proxy a Redirect URLs:
https://app.example.com/oauth2/callback -
En la pestaña OIDC/OAuth, establece:
- Token format:
JWT-Standard - Token group format:
Name (group), para que los grupos lleguen comodevsen lugar demy-org/devs
- Token format:
-
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_urles la URL de Casdoor, sin barra final. Debe ser exactamente elissuermostrado enhttps://door.example.com/.well-known/openid-configuration. Casdoor construye el emisor desdeoriginenconf/app.conf, o desde el host de la solicitud cuandooriginestá vacío; si ambos difieren, OAuth2 Proxy fallará conissuer did not match.cookie_secretdebe tener 16, 24 o 32 bytes, por ejemplo la salida deopenssl rand -base64 32 | tr -- '+/' '-_'.- Mantén el ámbito
profile: Casdoor devuelve grupos y roles desde su endpoint userinfo solo cuando se otorgaprofile. upstreamses 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 format | groups | roles | Unverified email |
|---|---|---|---|
JWT-Standard | from userinfo, group names | from userinfo, role names | signs in |
JWT-Custom | in the token if Groups is in Token fields | in the token if you add a token attribute roles (see below) | signs in |
JWT (default) | in the token | role objects, not usable for allowed_groups | rejected |
JWT-Empty | in the token | from userinfo, role names | signs 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:
| Name | Category | Value | Type |
|---|---|---|---|
roles | Existing Field | Roles | Array |
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):
| Header | Value |
|---|---|
X-Forwarded-User | Casdoor user ID (the sub claim) |
X-Forwarded-Preferred-Username | Nombre de usuario de Casdoor, p. ej. alice |
X-Forwarded-Email | Email address |
X-Forwarded-Groups | Groups (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
| Symptom | Cause and fix |
|---|---|
issuer did not match the issuer returned by provider at startup | oidc_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 verified | The 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-in | The 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 list | Add https://app.example.com/oauth2/callback to the application's Redirect URLs. |