Jenkins OIDC, Gitea OIDC y Grafana SSO con Casdoor: Un inicio de sesión para un stack DevOps autoalojado

Cada herramienta en un stack DevOps autoalojado típico puede actuar como cliente OpenID Connect: Gitea y Argo CD hablan OIDC nativamente, Jenkins lo hace mediante el plugin oic-auth, Grafana y Portainer mediante OAuth 2.0 genérico, y MinIO, Harbor y GitLab mediante sus configuraciones OIDC. Apunte todas ellas a una instancia de Casdoor, dé a cada herramienta su propia aplicación de Casdoor y coloque a su personal en grupos de Casdoor. Cada herramienta leerá entonces la afirmación groups y decidirá quién es administrador. Esta publicación enumera la URL de callback, las claves de configuración y el mapeo de grupos para cada herramienta, y luego cubre las partes que comparten.

El stack de un vistazo

Todas las rutas siguientes son relativas a la URL pública de la propia herramienta. Regístrelas en Redirect URLs de la aplicación de Casdoor para esa herramienta.

App	Protocol	Callback URL	Group/role to admin mapping	Casdoor doc
Gitea	OIDC (OAuth2 auth source)	/user/oauth2/<source-name>/callback	Sí: grupo admin, grupo restringido, map de equipos	Gitea
Jenkins	OIDC (oic-auth plugin)	/securityRealm/finishLogin, logout /OicLogout	Sí: grupos claim más seguridad basada en Matrix	Jenkins (OIDC)
Grafana	Generic OAuth 2.0	/login/generic_oauth	Sí: role_attribute_path	Grafana
Argo CD	OIDC	/auth/callback, CLI http://localhost:8085/auth/callback	Sí: argocd-rbac-cm	Argo CD
MinIO	OIDC	Console /oauth_callback	Políticas desde una claim (claim_name)	MinIO
Portainer	OAuth 2.0 (Custom)	La URL base de Portainer	Solo Business Edition	Portainer
Harbor	OIDC	/c/oidc/callback	Sí: OIDC Admin Group	Ninguna aún
GitLab	OIDC (OmniAuth)	/users/auth/openid_connect/callback	Premium y Ultimate: admin_groups	GitLab

El documento de descubrimiento que todo cliente OIDC necesita es https://<casdoor-host>/.well-known/openid-configuration. Si no ha conectado un cliente OIDC a Casdoor antes, Conectar un cliente OIDC estándar explica los endpoints.

Prepare Casdoor una vez

Antes de tocar las herramientas, configure tres cosas en Casdoor.

Grupos. Cree grupos como devops-admins y devops-users en el árbol de organizaciones y añada usuarios a ellos. Vea Grupos.

Formato de grupos del token. Por defecto, la afirmación groups nombra cada grupo como <organization>/<group>. La mayoría de las herramientas comparan la afirmación con una cadena simple que usted introduce, así que establezca Token group format en la pestaña OIDC/OAuth de cada aplicación a Name (group). La afirmación entonces lleva devops-admins. Las opciones se describen bajo Formato de grupo.

Formato de token. Mantenga Token format en JWT, el predeterminado. En ese formato, el ID token lleva groups, roles y tag. JWT-Empty y JWT-Standard dejan los tres fuera del token, y JWT-Custom los lleva solo si los selecciona en Token fields. La respuesta de /api/userinfo devuelve groups y los nombres de roles cuando se concede el scope profile, por lo que las herramientas que leen userinfo aún los ven.

Los roles también funcionan. En el formato JWT, la afirmación roles es una matriz de objetos de rol, por lo que coincida con roles[*].name. En /api/userinfo es una matriz simple de nombres. Vea Roles de usuario.

Gitea

En Site Administration, añada una fuente de autenticación de tipo OAuth2 con proveedor OpenID Connect, el ID de cliente y secreto, y la URL de descubrimiento de Casdoor. El nombre que dé a la fuente es parte de la URL de callback: una fuente llamada casdoor usa https://gitea.example.com/user/oauth2/casdoor/callback.

Para el mapeo de grupos, rellene Claim name providing group names con groups, luego Group Claim value for administrator users con devops-admins. Gitea también tiene Group Claim value for restricted users y Map claimed groups to Organization teams. La misma fuente desde la CLI:

gitea admin auth add-oauth \
  --name casdoor \
  --provider openidConnect \
  --key <client-id> \
  --secret <client-secret> \
  --auto-discover-url https://door.example.com/.well-known/openid-configuration \
  --group-claim-name groups \
  --admin-group devops-admins

Jenkins

Jenkins no tiene soporte OIDC propio. Instale el plugin OpenId Connect Authentication, elójalo como realm de seguridad y use la configuración well-known. El callback de inicio de sesión es /securityRealm/finishLogin y el callback de cierre de sesión es /OicLogout; añada ambos a Casdoor. En JCasC:

jenkins:
  securityRealm:
    oic:
      serverConfiguration:
        wellKnown:
          wellKnownOpenIDConfigurationUrl: https://door.example.com/.well-known/openid-configuration
      clientId: <client-id>
      clientSecret: <client-secret>
      userNameField: name
      fullNameFieldName: displayName
      emailFieldName: email
      groupsFieldName: groups
      logoutFromOpenidProvider: true
      properties:
      - "pkce"

El plugin solo pasa los grupos a Jenkins. Los derechos provienen de la estrategia de autorización: con seguridad basada en Matrix, cada fila de la tabla es un usuario o un grupo, así que añada una fila para devops-admins y dígale Overall/Administer. Elegir el plugin como realm de seguridad desactiva otros métodos de inicio de sesión, así que configure la propiedad escapeHatch del plugin (un nombre de usuario y secreto de respaldo) antes de guardar. Casdoor también tiene su propio plugin de Jenkins, descrito en Plugin de Jenkins, pero el plugin OIDC genérico es el que esta publicación asume.

Grafana

Grafana usa OAuth genérico. Su callback es /login/generic_oauth. El scopes predeterminado de Grafana es user:email, así que establezca explícitamente los scopes OIDC:

[auth.generic_oauth]
enabled = true
name = Casdoor
client_id = <client-id>
client_secret = <client-secret>
scopes = openid profile email
auth_url = https://door.example.com/login/oauth/authorize
token_url = https://door.example.com/api/login/oauth/access_token
api_url = https://door.example.com/api/userinfo
use_pkce = true
groups_attribute_path = groups
role_attribute_path = contains(groups[*], 'devops-admins') && 'Admin' || contains(groups[*], 'devops-users') && 'Editor' || 'Viewer'
role_attribute_strict = true

Grafana evalúa role_attribute_path contra el ID token primero, luego la respuesta de userinfo y después el access token. Los resultados válidos son None, Viewer, Editor, Admin y GrafanaAdmin; el último requiere allow_assign_grafana_admin = true. allowed_groups limita el inicio de sesión a los grupos listados y requiere groups_attribute_path. La sincronización de equipos es una función de Grafana Enterprise y Grafana Cloud.

Argo CD

Argo CD se comunica directamente con Casdoor, sin su Dex incluido. El callback del navegador es /auth/callback. argocd login --sso inicia un servidor local en el puerto 8085 por defecto y usa http://localhost:8085/auth/callback, por lo que debe registrarse también esa URL.

Configure url y oidc.config (con name, issuer, clientID, clientSecret, requestedScopes) en argocd-cm. Los requestedScopes predeterminados de Argo CD agregan un scope groups. Casdoor no lo necesita, porque el ID token JWT siempre lleva groups, por lo que nuestra guía solicita ["openid", "profile", "email"]. Los grupos se mapean en argocd-rbac-cm, donde scopes tiene como valor predeterminado [groups]:

data:
  policy.default: role:readonly
  policy.csv: |
    g, devops-admins, role:admin

La guía completa, incluyendo el client secret en argocd-secret, está en la guía de Argo CD.

MinIO

MinIO lee las políticas de una única claim, establecida con claim_name (predeterminado policy). No mapea grupos. El quickstart de Casdoor de MinIO y nuestra guía usan la claim tag de Casdoor: ponga un nombre de política de MinIO como readwrite en la Tag del usuario, y luego:

mc admin config set myminio identity_openid \
  config_url="https://door.example.com/.well-known/openid-configuration" \
  client_id=<client-id> client_secret=<client-secret> claim_name="tag"

role_policy es la alternativa: cada usuario que inicia sesión a través de este proveedor obtiene las políticas listadas, y no puede combinarse con claim_name. El callback de la Consola es <console-url>/oauth_callback. Detrás de un proxy, configure MINIO_BROWSER_REDIRECT_URL; la clave antigua redirect_uri está obsoleta. Tenga en cuenta que el repositorio de GitHub minio/minio ha sido archivado y su README indica que ya no se mantiene, así que verifique qué build de MinIO ejecuta antes de depender de estos ajustes.

Portainer

Portainer usa un proveedor Custom OAuth. Complete Authorization URL (/login/oauth/authorize), Access token URL (/api/login/oauth/access_token) y Resource URL (/api/userinfo) en su host de Casdoor, y establezca Redirect URL a la URL base de Portainer. También hay un campo Logout URL. En Portainer CE, Automatic team membership está marcado como una función de Business Edition, y la configuración que asigna derechos de administrador a los grupos solo está disponible en Business Edition. En CE, los usuarios creados por aprovisionamiento automático reciben el rol estándar de usuario y usted promueve administradores manualmente.

Harbor y GitLab

Harbor muestra su URI de redirección en la parte inferior de la página de configuraciones de OIDC: <harbor-url>/c/oidc/callback. Establezca OIDC Provider Endpoint a la URL de Casdoor, Group Claim Name a groups y OIDC Admin Group a devops-admins. Harbor lee la claim de grupo del ID token, que proporciona el formato JWT. Solo puede cambiar Harbor de autenticación por base de datos a autenticación OIDC antes de que existan usuarios locales.

Los docs de OIDC de GitLab tienen una sección de Casdoor y requieren que Casdoor sea servido sobre HTTPS. El callback es /users/auth/openid_connect/callback. Los roles basados en grupos (groups_attribute, admin_groups, required_groups, external_groups) requieren GitLab Premium o Ultimate.

Herramientas sin OIDC

Para paneles internos sin inicio de sesión propio, colóquelos detrás del plugin openid-connect de Apache APISIX (discovery, client_id, client_secret, redirect_uri, bearer_only), como en la guía de APISIX, o detrás de nginx como se describe en Autenticación SSO con Nginx.

Una aplicación por herramienta o una compartida

Una sola aplicación de Casdoor con el callback de cada herramienta en sus Redirect URLs funciona, pero una aplicación por herramienta es más fácil de gestionar:

• Cada herramienta tiene su propio client secret, por lo que un secreto de Jenkins filtrado no expone Grafana.
• Token group format, Token format y la caducidad del token son por aplicación, por lo que puede dar a Argo CD Name (group) sin cambiar las claims de otra herramienta.
• Casdoor verifica post_logout_redirect_uri contra las Redirect URLs de la aplicación, por lo que cada lista permanece corta y específica.

Los usuarios aún inician sesión una vez: después del primer inicio de sesión, la cookie de sesión de Casdoor permite que la redirección de la siguiente herramienta se complete sin solicitar contraseña.

Cierre de sesión

El endpoint de fin de sesión de Casdoor es /api/logout, listado como end_session_endpoint en el documento de discovery. Acepta id_token_hint, post_logout_redirect_uri, client_id y state, y solo redirige a una URL listada en las Redirect URLs de la aplicación. Cerrar sesión en Casdoor termina la sesión de Casdoor y los tokens de esa sesión, pero cada herramienta también mantiene su propia cookie de sesión. Configure el cierre de sesión en cada herramienta:

• Jenkins: logoutFromOpenidProvider, con /OicLogout registrado.
• Grafana: signout_redirect_url.
• Argo CD: logoutURL en oidc.config, por ejemplo https://door.example.com/api/logout?id_token_hint={{token}}&post_logout_redirect_uri={{logoutRedirectURL}}.
• Harbor: OIDC Session Logout.
• Portainer: Logout URL.

Los detalles del endpoint están en RP-initiated logout.

Referencias

• Gitea: Authentication, admin auth add-oauth
• Jenkins: OpenId Connect Authentication plugin, configuration reference, Managing security
• Grafana: Configure generic OAuth2 authentication
• Argo CD: User management, RBAC, argocd login
• MinIO: Casdoor quickstart in the MinIO repository
• Portainer: Autenticación OAuth
• Harbor: Configurar autenticación de proveedor OIDC
• GitLab: Usar OpenID Connect como proveedor de autenticación
• Apache APISIX: Plugin openid-connect