Jenkins OIDC, Gitea OIDC und Grafana SSO mit Casdoor: Ein Login für einen selbst gehosteten DevOps-Stack

Jedes Tool in einem typischen selbst gehosteten DevOps-Stack kann als OpenID Connect Client fungieren: Gitea und Argo CD unterstützen OIDC nativ, Jenkins über das oic-auth Plugin, Grafana und Portainer über generisches OAuth 2.0, und MinIO, Harbor sowie GitLab über ihre OIDC-Einstellungen. Richten Sie alle auf eine Casdoor-Instanz aus, weisen Sie jedem Tool seine eigene Casdoor-Anwendung zu und ordnen Sie Ihre Benutzer Casdoor-Gruppen zu. Jedes Tool liest dann den groups-Claim und entscheidet, wer ein Administrator ist. Dieser Artikel listet die Callback-URL, die Konfigurationsschlüssel und die Gruppenzuordnung für jedes Tool auf und behandelt anschließend die gemeinsamen Teile.

Der Stack im Überblick

Alle untenstehenden Pfade sind relativ zur öffentlichen URL des jeweiligen Tools. Tragen Sie diese unter Redirect URLs der Casdoor-Anwendung für dieses Tool ein.

App	Protokoll	Callback-URL	Gruppen-/Rollen-zu-Admin-Zuordnung	Casdoor-Doku
Gitea	OIDC (OAuth2 Auth Source)	/user/oauth2/<source-name>/callback	Ja: Admin-Gruppe, eingeschränkte Gruppe, Team-Mapping	Gitea
Jenkins	OIDC (oic-auth Plugin)	/securityRealm/finishLogin, Logout /OicLogout	Ja: groups Claim plus Matrix-basierte Sicherheit	Jenkins (OIDC)
Grafana	Generisches OAuth 2.0	/login/generic_oauth	Ja: role_attribute_path	Grafana
Argo CD	OIDC	/auth/callback, CLI http://localhost:8085/auth/callback	Ja: argocd-rbac-cm	Argo CD
MinIO	OIDC	Console /oauth_callback	Richtlinien aus einem Claim (claim_name)	MinIO
Portainer	OAuth 2.0 (Custom)	Die Portainer-Basis-URL	Nur Business Edition	Portainer
Harbor	OIDC	/c/oidc/callback	Ja: OIDC Admin Group	noch keine
GitLab	OIDC (OmniAuth)	/users/auth/openid_connect/callback	Premium und Ultimate: admin_groups	GitLab

Das Discovery-Dokument, das jeder OIDC-Client benötigt, lautet https://<casdoor-host>/.well-known/openid-configuration. Falls Sie noch keinen OIDC-Client mit Casdoor verbunden haben, erklärt Connect a standard OIDC client die Endpunkte.

Casdoor einmalig vorbereiten

Bevor Sie die Tools konfigurieren, richten Sie drei Dinge in Casdoor ein.

Groups. Erstellen Sie Gruppen wie devops-admins und devops-users im Organisationsbaum und fügen Sie Benutzer hinzu. Siehe Groups.

Token group format. Standardmäßig benennt der groups-Claim jede Gruppe als <organization>/<group>. Die meisten Tools vergleichen den Claim mit einer einfachen Zeichenkette, die Sie eingeben. Stellen Sie daher Token group format im Tab OIDC/OAuth jeder Anwendung auf Name (group). Der Claim enthält dann devops-admins. Die Optionen sind unter Group format beschrieben.

Token format. Belassen Sie Token format bei JWT, dem Standardwert. In diesem Format enthält das ID-Token groups, roles und tag. JWT-Empty und JWT-Standard lassen alle drei aus dem Token weg, und JWT-Custom enthält sie nur, wenn Sie sie unter Token fields auswählen. Die /api/userinfo-Antwort gibt groups und die Rollennamen zurück, wenn der profile Scope gewährt wird, sodass Tools, die Userinfo lesen, diese weiterhin sehen.

Rollen funktionieren ebenfalls. Im JWT-Format ist der roles-Claim ein Array von Rollenobjekten, daher sollten Sie auf roles[*].name prüfen. In /api/userinfo ist es ein einfaches Array von Namen. Siehe User roles.

Gitea

Fügen Sie unter Site Administration eine Authentifizierungsquelle vom Typ OAuth2 mit Anbieter OpenID Connect, der Client-ID und dem Secret sowie der Casdoor-Discovery-URL hinzu. Der Name, den Sie der Quelle geben, ist Teil der Callback-URL: Eine Quelle namens casdoor verwendet https://gitea.example.com/user/oauth2/casdoor/callback.

Für die Gruppenzuordnung füllen Sie Claim name providing group names mit groups aus, gefolgt von Group Claim value for administrator users mit devops-admins. Gitea hat zudem Group Claim value for restricted users und Map claimed groups to Organization teams. Dieselbe Quelle über die 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 hat keine eigene OIDC-Unterstützung. Installieren Sie das Plugin OpenId Connect Authentication, wählen Sie es als Sicherheitsrealm aus und verwenden Sie die Well-Known-Konfiguration. Der Login-Callback ist /securityRealm/finishLogin und der Logout-Callback ist /OicLogout; fügen Sie beide zu Casdoor hinzu. In 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"

Das Plugin übergibt die Gruppen nur an Jenkins. Rechte stammen aus der Autorisierungsstrategie: Bei Matrix-basierter Sicherheit ist jede Zeile der Tabelle ein Benutzer oder eine Gruppe, also fügen Sie eine Zeile für devops-admins hinzu und geben Sie ihr Overall/Administer. Wenn Sie das Plugin als Sicherheitsrealm auswählen, werden andere Login-Methoden deaktiviert, daher konfigurieren Sie die escapeHatch-Eigenschaft des Plugins (ein Fallback-Benutzername und Secret), bevor Sie speichern. Casdoor hat auch ein eigenes Jenkins-Plugin, das in Jenkins plugin beschrieben ist, aber das generische OIDC-Plugin ist dasjenige, von dem dieser Artikel ausgeht.

Grafana

Grafana verwendet generisches OAuth. Sein Callback ist /login/generic_oauth. Grafunas Standard-scopes ist user:email, daher sollten Sie die OIDC-Scopes explizit setzen:

[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 wertet role_attribute_path zuerst gegen das ID-Token, dann die Userinfo-Antwort und schließlich das Access-Token aus. Gültige Ergebnisse sind None, Viewer, Editor, Admin und GrafanaAdmin; letzteres erfordert allow_assign_grafana_admin = true. allowed_groups beschränkt den Login auf die aufgelisteten Gruppen und erfordert groups_attribute_path. Team-Sync ist eine Funktion von Grafana Enterprise und Grafana Cloud.

Argo CD

Argo CD kommuniziert direkt mit Casdoor, ohne seinen gebündelten Dex. Der Browser-Callback ist /auth/callback. argocd login --sso startet standardmäßig einen lokalen Server auf Port 8085 und verwendet http://localhost:8085/auth/callback, daher registrieren Sie auch diese URL.

Legen Sie url und oidc.config (mit name, issuer, clientID, clientSecret, requestedScopes) in argocd-cm fest. Die standardmäßigen requestedScopes von Argo CD fügen einen groups-Scope hinzu. Casdoor benötigt dies nicht, da das JWT-ID-Token immer groups enthält, daher fordert unser Leitfaden ["openid", "profile", "email"] an. Gruppen werden in argocd-rbac-cm abgebildet, wobei scopes standardmäßig [groups] ist:

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

Die vollständige Anleitung, einschließlich des Client-Secrets in argocd-secret, finden Sie im Argo CD-Leitfaden.

MinIO

MinIO liest Richtlinien aus einem einzelnen Claim, der mit claim_name (Standard policy) festgelegt wird. Es bildet keine Gruppen ab. Sowohl der MinIO-Casdoor-Quickstart als auch unser Leitfaden verwenden den tag-Claim von Casdoor: Legen Sie einen MinIO-Richtliniennamen wie readwrite im Tag des Benutzers ab, und setzen Sie dann:

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 ist die Alternative: Jeder Benutzer, der sich über diesen Provider anmeldet, erhält die aufgelisteten Richtlinien, und es kann nicht mit claim_name kombiniert werden. Der Console-Callback ist <console-url>/oauth_callback. Hinter einem Proxy setzen Sie MINIO_BROWSER_REDIRECT_URL; der alte redirect_uri-Schlüssel ist veraltet. Beachten Sie, dass das GitHub-Repository minio/minio archiviert wurde und dessen README angibt, dass es nicht mehr gewartet wird. Prüfen Sie daher, welche MinIO-Version Sie ausführen, bevor Sie sich auf diese Einstellungen verlassen.

Portainer

Portainer verwendet einen Custom OAuth-Provider. Füllen Sie auf Ihrem Casdoor-Host Authorization URL (/login/oauth/authorize), Access token URL (/api/login/oauth/access_token) und Resource URL (/api/userinfo) aus und legen Sie Redirect URL auf die Basis-URL von Portainer fest. Es gibt auch ein Feld für die Logout URL. In Portainer CE ist Automatic team membership als Business Edition-Funktion gekennzeichnet, und die Einstellung, die Gruppen Administratorrechte zuweist, ist nur in der Business Edition verfügbar. Bei CE erhalten Benutzer, die durch automatische Provisionierung erstellt wurden, die Standard-Benutzerrolle, und Sie befördern Administratoren manuell.

Harbor und GitLab

Harbor zeigt seine Redirect-URI unten auf der OIDC-Einstellungsseite an: <harbor-url>/c/oidc/callback. Setzen Sie OIDC Provider Endpoint auf die Casdoor-URL, Group Claim Name auf groups und OIDC Admin Group auf devops-admins. Harbor liest den Gruppen-Claim aus dem ID-Token, was das JWT-Format bereitstellt. Sie können Harbor nur vor dem Anlegen lokaler Benutzer von Datenbank- auf OIDC-Authentifizierung umstellen.

Die OIDC-Dokumentation von GitLab hat einen Casdoor-Abschnitt und erfordert, dass Casdoor über HTTPS bereitgestellt wird. Der Callback ist /users/auth/openid_connect/callback. Gruppenbasierte Rollen (groups_attribute, admin_groups, required_groups, external_groups) erfordern GitLab Premium oder Ultimate.

Tools ohne OIDC

Für interne Dashboards ohne eigenes Login stellen Sie sie hinter das openid-connect-Plugin von Apache APISIX (discovery, client_id, client_secret, redirect_uri, bearer_only), wie im APISIX-Leitfaden beschrieben, oder hinter nginx, wie in Nginx SSO authentication erläutert.

Eine Anwendung pro Tool oder eine gemeinsame

Eine einzelne Casdoor-Anwendung mit allen Callback-URLs der Tools in ihren Redirect URLs funktioniert, aber eine Anwendung pro Tool ist einfacher zu betreiben:

• Jedes Tool erhält sein eigenes Client-Secret, sodass ein geleaktes Jenkins-Secret nicht Grafana exponiert.
• Token group format, Token format und Token-Ablaufdatum sind pro Anwendung definiert, sodass Sie Argo CD Name (group) geben können, ohne die Claims anderer Tools zu ändern.
• Casdoor prüft post_logout_redirect_uri gegen die Redirect URLs der Anwendung, sodass jede Liste kurz und spezifisch bleibt.

Benutzer melden sich weiterhin nur einmal an: Nach der ersten Anmeldung ermöglicht das Session-Cookie von Casdoor, dass die Weiterleitung zum nächsten Tool ohne Passwortabfrage abgeschlossen wird.

Abmeldung

Der End-Session-Endpoint von Casdoor ist /api/logout, der im Discovery-Dokument als end_session_endpoint aufgeführt ist. Er akzeptiert id_token_hint, post_logout_redirect_uri, client_id und state und leitet nur auf eine URL weiter, die in den Redirect URLs der Anwendung aufgeführt ist. Das Abmelden bei Casdoor beendet die Casdoor-Session und die Tokens dieser Session, aber jedes Tool behält auch sein eigenes Session-Cookie. Richten Sie den Logout in jedem Tool ein:

• Jenkins: logoutFromOpenidProvider, mit registriertem /OicLogout.
• Grafana: signout_redirect_url.
• Argo CD: logoutURL in oidc.config, z. B. https://door.example.com/api/logout?id_token_hint={{token}}&post_logout_redirect_uri={{logoutRedirectURL}}.
• Harbor: OIDC Session Logout.
• Portainer: Logout URL.

Die Details des Endpoints finden Sie unter RP-initiated logout.

Referenzen

• 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: OAuth-Authentifizierung
• Harbor: OIDC-Anbieter-Authentifizierung konfigurieren
• GitLab: OpenID Connect als Authentifizierungsanbieter verwenden
• Apache APISIX: openid-connect-Plugin