Integrations-Anleitung · Nextcloud

Nextcloud Single Sign-On mit CodeB.

Den OpenID-Connect-Provider von CodeB als Identitätsquelle für eine Self-hosted-Nextcloud nutzen. Ein Konto, ein Passwort, Auto-Provisioning beim ersten Login und Gruppen-Mapping pro Nutzer, gesteuert aus der CodeB-Admin-UI. Cookie-frei, PKCE-only, keine Client-Secrets zum Rotieren.

Zeit bis zum ersten Login: ca. 10 Minuten, inklusive Nextcloud-App-Installation. Funktioniert mit jeder Nextcloud-Version, die die user_oidc-App mitbringt (Nextcloud 24+).

Lesen Sie das, bevor Sie OIDC an einen bestehenden Nextcloud-Nutzer hängen. Sowohl user_oidc als auch die Social-Login-App überschreiben standardmäßig die Nextcloud-Gruppen eines Nutzers bei jeder Anmeldung mit dem, was der IdP im groups-Claim sendet. Hängen Sie OIDC an einen Nutzer mit sorgfältig gepflegten lokalen Gruppen (Adminrechte, Ordner-ACLs, Bezahl-Gruppe usw.), sträubt der nächste Sign-in diese Gruppen ab und ersetzt sie durch das, was CodeB sendet. Ausgesperrte Admins und verlorene Berechtigungen sind die üblichen Folgen.

Zwei sichere Wege — entscheiden Sie sich vor dem ersten OIDC-Sign-in für einen:

Aus CodeB keine Gruppen emittieren. In register.html die betroffenen Nutzer bearbeiten und das Feld Groups leer lassen. Ohne groups-Claim im Token hat Nextcloud nichts, womit die lokalen Gruppen überschrieben werden könnten. (Empfohlen, wenn Nextcloud die Source of Truth für Gruppen ist.)
Group-Sync in der Nextcloud-App deaktivieren. Siehe Abschnitt 7. Gruppen pro Nutzer — der genaue Toggle unterscheidet sich zwischen user_oidc und Social Login.

In jedem Fall entscheiden, wer die Gruppenmitgliedschaft besitzt (Nextcloud oder CodeB), bevor der Nutzer sich anmeldet. Nicht erst hart lernen, nachdem die Admin-Gruppe weg ist.

Inhalt

Voraussetzungen
user_oidc-App installieren
Nextcloud-Client auf CodeB registrieren
Provider in Nextcloud anlegen (user_oidc)
Alternative: Social-Login-App (Custom OIDC)
Claims mappen
Gruppen pro Nutzer
Round-Trip testen
Aus einem CodeB-Nutzer einen Nextcloud-Admin machen
Fehlersuche

1. Voraussetzungen

HTTPS auf beiden Seiten. Der CodeB-IdP erzwingt HTTPS für jede Nicht-Loopback-Redirect-URI; die Callback-URL von Nextcloud muss ebenfalls HTTPS sein.
Nextcloud aus einem Browser erreichbar. Der Flow ist browserbasiert; Nextcloud spricht nicht direkt mit dem IdP — der Browser des Nutzers vermittelt.
Betreiberzugriff auf den CodeB-Host. Sie legen eine Datei (clients.json) auf der IIS-Maschine an. Kein Neustart nötig — die Datei wird hot-reloaded.
Ein CodeB-Benutzerkonto für den Test. Über register.html anlegen, falls noch keines existiert.

2. user_oidc-App installieren

In Nextcloud auf Apps (Nutzer-Menü oben rechts) gehen und nach OpenID Connect user backend suchen. Auf Herunterladen und aktivieren klicken. Nach der Installation erscheint ein neuer OpenID Connect-Abschnitt unter Einstellungen → Verwaltung → Authentifizierung.

Die App ist offiziell von der Nextcloud GmbH gepackagt und der empfohlene Weg. Hat Ihre Nextcloud bereits die Social-Login-App (sociallogin) installiert und Sie wollen dabei bleiben, springen Sie zu Alternative: Social-Login-App — das funktioniert ebenfalls, nur mit anderem Feldlayout.

3. Nextcloud-Client auf CodeB registrieren

Der CodeB-IdP verlangt eine Vorab-Registrierung jedes Relying Party. Ohne Eintrag liefert er invalid_client.

Auf dem IIS-Host, auf dem CodeB läuft, eine JSON-Datei ablegen unter:

D:\<ihre-codeb-installation>\App_Data\<tenant-domain>\oidc\clients.json

Bei der öffentlichen Installation auf phone.codeb.io lautet der Pfad zum Beispiel D:\aloaha\phone\App_Data\phone.codeb.io\oidc\clients.json. Inhalt:

{ "clients": [ { "client_id": "nextcloud", // client_secret NUR setzen, wenn Ihre Nextcloud-App eines benutzt // (Social Login ja; user_oidc nutzt PKCE und kommt ohne aus). "client_secret": "DURCH_EINEN_STARKEN_ZUFALLS_64_ZEICHEN_WERT_ERSETZEN", "redirect_uris": [ "https://<ihre-nextcloud>/index.php/apps/sociallogin/custom_oidc/CodeBSSO", "https://<ihre-nextcloud>/index.php/apps/user_oidc/code", "https://<ihre-nextcloud>/apps/user_oidc/code" ], "description": "Nextcloud (Social Login + user_oidc)" } ] }

Sowohl /index.php/apps/user_oidc/code als auch /apps/user_oidc/code sind aufgelistet, damit dieselbe Datei funktioniert, unabhängig davon, ob in Ihrer Nextcloud Pretty-URL-Rewriting aktiv ist. Den Port mit aufnehmen (z. B. :8443), wenn Ihre Nextcloud nicht auf dem Standard-HTTPS-Port läuft.

Verwenden Sie stattdessen die Social-Login-App, dann hängen Sie deren Callback-URL in dasselbe redirect_uris-Array (ein Client-Eintrag kann beliebig viele URIs auflisten). Das URL-Muster der Social-Login-App lautet /index.php/apps/sociallogin/custom_oidc/<InternalName> — <InternalName> durch das ersetzen, was Sie in dieses Feld eintragen (z. B. CodeBSSO).

Datei speichern. Kein IIS-Recycle nötig — der IdP prüft die mtime und lädt sie beim nächsten OIDC-Request neu.

Der eingebaute Client codeb-admin ist immer verfügbar (auto-gebunden an https://<tenant>/oidc-callback.html) und muss nicht in clients.json gelistet werden. Nur Drittanbieter-RPs eintragen.

4. Provider in Nextcloud anlegen (user_oidc-App)

In Nextcloud: Einstellungen → Verwaltung → Authentifizierung → OpenID Connect → Neuen Provider registrieren. Das Formular ausfüllen:

Feld	Wert
Identifier	`codeb` (oder ein beliebiges Kurzlabel; erscheint auf dem Login-Button)
Client ID	`nextcloud` (muss mit `clients.json` übereinstimmen)
Client-Secret	leer lassen — CodeB ist PKCE-only-Public-Client
Discovery-Endpunkt	`https://phone.codeb.io/.well-known/openid-configuration` (oder Ihr CodeB-Host)
Scope	`openid profile email`
PKCE verwenden	an (S256). Pflicht.
Token-Endpunkt-Auth-Methode	`none`
id_token_hint beim Logout senden	an (empfohlen)

Speichern. Nextcloud holt das Discovery-Dokument und JWKS, um zu bestätigen, dass der Provider erreichbar ist.

5. Alternative: Social-Login-App (Custom OpenID Connect)

Wenn Ihre Nextcloud die Social-Login-App (sociallogin von zorn-v) statt user_oidc nutzt, hat das Formular andere Feldnamen, aber denselben Flow. Einstellungen → Verwaltung → Social Login → Custom OpenID Connect → Hinzufügen.

Der Custom-OIDC-Provider der Social-Login-App verwendet kein PKCE — er spricht klassisches OAuth 2.0 mit client_secret. Registrieren Sie den Nextcloud-Client in CodeB als confidential (client_secret in clients.json setzen) und tragen exakt denselben Wert in das Social-Login-Formular ein. Der IdP schaltet automatisch in den client_secret_post-Modus, sobald ein Secret registriert ist.

Feld	Wert
Internal name	`CodeBSSO` (beliebiger Kurz-Identifier; nur intern verwendet)
Title	`CodeB SSO` (erscheint auf dem Login-Button)
Authorize-URL	https://<codeb-host>/oidc.ashx?action=authorize
Token-URL	https://<codeb-host>/oidc.ashx?action=token
Display-Name-Claim	`name`
UserInfo-URL	https://<codeb-host>/oidc.ashx?action=userinfo
Logout-URL	https://<codeb-host>/oidc.ashx?action=end_session
Client-ID	`nextcloud` (muss mit `clients.json` aus Schritt 3 übereinstimmen)
Client-Secret	Ein starker Zufallswert — mindestens 32 Zufallszeichen (z. B. `openssl rand -base64 48` oder ein Passwortmanager). Denselben String in das `client_secret`-Feld der `clients.json` auf CodeB-Seite einfügen. CodeB vergleicht beide konstantzeitlich bei jedem `/token`-Aufruf.
Scope	`openid profile email`
Groups-Claim	`groups`
Button-Style	frei wählbar (rein kosmetisch)
Default group	None stehen lassen. Der `groups`-Claim von CodeB trägt die Mitgliedschaft bereits.

Gruppen-Mapping (CodeB → Nextcloud)

Mit dem Button Gruppen-Mapping hinzufügen übersetzen Sie die von CodeB emittierten Gruppennamen in die Nextcloud-Gruppennamen. Zwei Wege:

Pass-through: leer lassen. Die CodeB-Gruppen (admin, user, siponly, guest plus eigene Gruppen pro Nutzer) werden in Nextcloud automatisch angelegt, und der Nutzer tritt ihnen wörtlich bei.
Explizit mappen: eine Zeile pro Paar. Am häufigsten: die CodeB-Gruppe admin auf die eingebaute Nextcloud-Gruppe admin mappen, damit CodeB-Admins volle Nextcloud-Rechte bekommen. Beispielzeilen:
CodeB Nextcloud admin -> admin finance -> Finance Team ops -> Operations

Die Logout-URL ist optional — CodeB ist cookie-frei, es gibt also keine IdP-seitige Session zu räumen. Das Feld zu füllen erlaubt Nextcloud trotzdem, den Browser zu end_session zu schicken für einen sauberen Exit. Empfohlen.

Speichern. Aus Nextcloud abmelden, zur Login-Seite zurück, und auf den CodeB SSO-Button (Titel wie eingetragen) klicken. Der Rest des Flows ist identisch zur user_oidc-Variante — dasselbe CodeB-Login-Formular, dasselbe Auto-Provisioning, dieselbe Gruppen-Propagation pro Nutzer.

6. Claims mappen

Weiter unten auf der Provider-Seite zeigt Nextcloud einen Claim-Mapping-Abschnitt. Setzen:

Mapping	Claim	Was CodeB sendet
Benutzer-ID	`sub`	Der CodeB-Username (z. B. `alice`). Stabil, wird als Nextcloud-Konto-ID verwendet.
Anzeigename	`name`	Aus dem OIDC-Profil (das Feld Full name in CodeBs register.html).
E-Mail	`email`	Aus dem OIDC-Profil. Pflegen Sie das — Nextcloud-Benachrichtigungen hängen daran.
Quota	leer lassen	CodeB emittiert keinen Quota-Claim.
Gruppen	`groups`	Array aus Strings. Default ist ein einelementiges Array mit der Rolle (`["admin"]`, `["user"]` usw.). Pro Nutzer überschreibbar (s. nächsten Abschnitt).

Zum Schluss Auto-Provisioning aktivieren (oder wie der Schalter in Ihrer Nextcloud-Version heißt). Meldet sich ein CodeB-Nutzer das erste Mal an, legt Nextcloud das lokale Konto on the fly an.

7. Gruppen pro Nutzer

CodeB hat vier eingebaute Rollen (admin / user / siponly / guest), die als einelementiges Array im groups-Claim ankommen. Das reicht für einfache Fälle, ist aber in Nextcloud selten das, was man will — Gruppenzugehörigkeit steuert dort Freigaben, Talk-Berechtigungen, Dateigrößenquoten usw.

Pro Nutzer in der CodeB-Admin-UI überschreiben. In register.html auf Bearbeiten klicken, zum Groups-Abschnitt scrollen und eine Komma-separierte Liste eingeben:

finance, nextcloud-admin, ops

Speichern. Ab dem nächsten Sign-in kommt der groups-Claim als ["finance", "nextcloud-admin", "ops"] in Nextcloud an statt des aus der Rolle abgeleiteten Defaults. Die user_oidc-App legt nicht existierende Nextcloud-Gruppen automatisch an und weist den Nutzer entsprechend zu.

Beschränkungen: bis zu 32 Gruppen pro Nutzer, je 1–64 Zeichen aus a-zA-Z0-9_.-. Leere Liste bedeutet „zurück zum Role-als-Gruppe-Default“.

Bestehende Gruppenmitgliedschaften nicht überschreiben

Beide Nextcloud-OIDC-Apps schreiben die gesamte Gruppenliste des Nutzers bei jedem Login standardmäßig neu. Wenn der Nutzer bereits Nextcloud-Gruppen hat, die OIDC nicht anrühren soll (Admin, Share-Empfänger, Lizenz-Gruppen), wählen Sie EINE der beiden Haltungen unten vor dem ersten OIDC-Sign-in.

Haltung A — Nextcloud besitzt Gruppen, CodeB emittiert keine

Das ist der einfachste Weg. In register.html das Groups-Feld leer lassen für alle Nutzer, deren Nextcloud-Gruppen nicht überschrieben werden sollen. Ohne gefülltes Groups-Feld fällt CodeB auf ein einelementiges [role]-Array zurück. Um auch das zu unterdrücken, lässt sich auf Nextcloud-Seite ein Scope wählen, der groups ausschließt — einfacher ist aber die nächste Haltung.

Haltung B — aus CodeB Gruppen emittieren, Sync in Nextcloud abschalten

Unterschiedlicher Toggle pro App:

App	Einstellung AUS	Wo
`user_oidc`	Aktualisierte Benutzerinformationen beim Login vom IdP übernehmen → Groups abschalten	Einstellungen → Verwaltung → OpenID Connect → Provider → Mappings (die „Beim Login aktualisieren“-Checkbox-Zeile beim Groups-Mapping)
Social Login	Benutzerprofil bei jedem Login aktualisieren deaktivieren UND das Groups-Claim-Feld leeren (oder auf einen ungenutzten Claim-Namen wie `nogroups` setzen)	Einstellungen → Verwaltung → Social Login → Custom-OIDC-Provider → Formularende

Mit dem Toggle aus authentifiziert der OIDC-Login den Nutzer weiterhin und aktualisiert Anzeigename + E-Mail, wenn diese Mappings an sind, lässt aber die Gruppenmitgliedschaft in Ruhe. Gruppenänderungen werden dann in Nextcloud selbst verwaltet.

Vor Live-Schaltung testen. Erst mit einem Wegwerf-Testnutzer anmelden — einem, dessen Gruppenverlust verkraftbar ist. In Einstellungen → Benutzer prüfen, dass die Gruppen wie erwartet stehen. Erst danach OIDC für echte Konten aktivieren.

8. Round-Trip testen

Ein Inkognito-Nextcloud-Tab öffnen und auf Mit codeb anmelden klicken (das Label aus Schritt 4).
Der Browser springt zu https://phone.codeb.io/login.html.
CodeB-Username + Passwort eingeben. Der Browser hasht das Passwort lokal zu HA1 und postet nur den Hash — CodeB sieht den Klartext nie.
Bei Erfolg landen Sie zurück in Nextcloud, angemeldet. Beim ersten Login wird automatisch ein Nextcloud-Konto mit den obigen Claims angelegt.

Prüfen in Nextcloud: Das Nutzer-Menü oben rechts zeigt Anzeigename und E-Mail. Einstellungen → Verwaltung → Benutzer zeigt den neuen Nutzer mit dem OIDC-Backend-Label und den konfigurierten Gruppen.

9. Aus einem CodeB-Nutzer einen Nextcloud-Admin machen

Die eingebaute Gruppe admin in Nextcloud erteilt volle Adminrechte. Um einen CodeB-Nutzer dort hineinzumappen, admin als eine seiner Gruppen in CodeB eintragen:

admin, ops

Damit landet er beim nächsten Sign-in in der Nextcloud-Gruppe admin. (Die eingebaute „admin“-Gruppe ist eine ganz normale Gruppe mit speziellen Privilegien — der groups-Claim erzeugt die Mitgliedschaft genauso wie für jede andere Gruppe.)

Das nicht mit dem CodeB-role-Claim verwechseln. Ein CodeB-Nutzer mit role: "user", der admin in seiner Groups-Liste hat, wird Nextcloud-Admin, ist aber weiterhin Nicht-Admin in den CodeB-Admin-Seiten. Die beiden Berechtigungsmodelle sind unabhängig.

10. Fehlersuche

Symptom	Ursache
`invalid_client` bei `/authorize`	Die `client_id` steht nicht in `clients.json` oder die `redirect_uri` von Nextcloud matcht keinen der registrierten URIs byteweise. In `data/nextcloud.log` die exakte URI nachsehen und in `clients.json` nachtragen.
Social Login: `invalid_client` ohne klare Ursache	Die Social-Login-App postet zurück an `https://<nextcloud>/index.php/apps/sociallogin/custom_oidc/CodeBSSO` (wobei `CodeBSSO` Ihr Internal name ist). Diese vollständige URL muss im `redirect_uris`-Array Ihrer `clients.json` stehen. Beim Umbenennen des Internal name ändert sich auch die Redirect-URI.
Social Login: `invalid_request` bei `/authorize`	CodeB hält den Client weiterhin für Public-PKCE-only, Social Login sendet aber keine `code_challenge`. Ein nicht-leeres `client_secret` in den Client-Eintrag der `clients.json` setzen — der IdP behandelt den Client dann als confidential und akzeptiert die Anfrage ohne PKCE.
Social Login: `invalid_client: client_secret invalid`	Das Secret im Nextcloud-Provider-Formular passt nicht zum `client_secret` in `clients.json`. Beide müssen byteweise identisch sein. Vorsicht mit Leerzeichen am Ende und Anführungszeichen beim Copy-Paste.
`invalid_grant: PKCE verifier invalid`	Sicherstellen, dass Use PKCE in den Nextcloud-Provider-Einstellungen an ist. Ohne PKCE lehnt der IdP den Auth-Code ab.
„Could not load user“ nach Sign-in	Auto-Provisioning ist aus. In den Provider-Einstellungen einschalten und nochmal versuchen.
Nutzer angelegt, aber keine E-Mail / kein Name	Das CodeB-Profil hat E-Mail / Name nicht gesetzt. Nutzer in register.html bearbeiten, Felder füllen, erneut anmelden.
Gruppen erscheinen nicht in Nextcloud	(a) Das Groups-Claim-Mapping muss in Schritt 5 auf `groups` stehen. (b) Bei pro-Nutzer-Override: Namen prüfen gegen die Beschränkung (a-z A-Z 0-9 _ . -). (c) Nextcloud aktualisiert Gruppen nur bei jedem Sign-in; einmal abmelden und neu anmelden.
`429 rate_limited` beim Testen	Der CodeB-Login-Endpunkt erlaubt 10 fehlgeschlagene Versuche pro IP und Minute. Eine Minute warten (`Retry-After` beachten) und nochmal.

Hilfe nötig? Melden Sie sich — wir betreiben Nextcloud-SSO mit CodeB produktiv und helfen beim Debuggen Ihrer Installation.