So konfigurieren Sie Keycloak als Identitätsanbieter für ownCloud Infinite Scale

Diese Anleitung verbindet ownCloud Infinite Scale (oCIS) mit Keycloak über OpenID Connect (OIDC), die auf OAuth 2.0 basierende Identitätsschicht. Keycloak authentifiziert Benutzer; oCIS vertraut den von Keycloak ausgegebenen signierten Identitäts- und Zugriffsinformationen. Die browserbasierte Anmeldung verwendet HTTPS-Weiterleitungen, während oCIS zusätzlich die Discovery- und Signing-Key-Endpunkte von Keycloak erreichen muss.

Stand 6. Oktober 2026 beschreibt die aktuelle Administrationsdokumentation von ownCloud diese Einstellungen unter Infinite Scale 9.0. Das offizielle Keycloak-Bereitstellungsbeispiel ist ein guter Ausgangspunkt, jedoch können sich die Compose-Datei und der Realm-Export ändern. Verwenden Sie kompatible Image-Versionen und überprüfen Sie die bereitgestellten Dateien, anstatt ein Beispiel ohne Versionsangabe blind zu kopieren.

Was Sie vor der Konfiguration von OIDC benötigen

Bereiten Sie die öffentliche HTTPS-Adresse für oCIS (z. B. https://cloud.example.com) und die öffentliche HTTPS-Adresse für Keycloak (z. B. ) vor https://sso.example.com. Beide Namen müssen von den Browsern der Benutzer korrekt aufgelöst werden können. Der oCIS-Server muss außerdem die OIDC-Metadaten und die öffentlichen Signaturschlüssel von Keycloak erreichen können. Falls ein Reverse-Proxy vorgeschaltet ist, konfigurieren Sie dessen öffentlichen Hostnamen und die weitergeleiteten Header einheitlich.

• Eine funktionierende ownCloud Infinite Scale-Bereitstellung und Administratorzugriff auf die Umgebung oder Compose-Konfiguration.
• Ein funktionierender Keycloak-Realm und Administratorzugriff. Ein Realm ist ein Keycloak-Namensraum für Benutzer, Clients, Rollen und Identitätseinstellungen.
• Ein vom Browser und vom Server, der das TLS-Zertifikat von Keycloak validiert, als vertrauenswürdig eingestuftes TLS-Zertifikat. Im Produktivbetrieb sollte die Zertifikatsprüfung nicht deaktiviert werden.
• Eine Entscheidung bezüglich des Account-Matchings: Bestehende oCIS-Benutzer mit stabilen Identitätsansprüchen verbinden oder die Bereitstellung von First-Login-Accounts mit dem erforderlichen schreibfähigen Benutzer-Backend ermöglichen.

1. Ermitteln Sie den genauen Keycloak-Aussteller.

In Keycloak ist der OIDC-Aussteller normalerweise die Realm-URL, nicht die URL der Administrationskonsole und nicht die URL des Discovery-Dokuments. Für einen Realm mit dem Namen „<Realm-Name>“ teamkönnte dies beispielsweise so aussehen https://sso.example.com/realms/team: „<Realm-Name>“. Bei älteren Installationen oder Bereitstellungen mit einem Pfadpräfix kann dies abweichen. Erstellen Sie den Wert daher nicht aus dem Speicher. Öffnen Sie das Discovery-Dokument des Realms unter „<Realm-Name>“ https://sso.example.com/realms/team/.well-known/openid-configurationund kopieren Sie den Wert der zugehörigen issuerEigenschaft exakt.

Von einem Server, der Keycloak erreichen kann, können Sie das Dokument mit folgendem Befehl untersuchen:

curl -fsS https://sso.example.com/realms/team/.well-known/openid-configuration

Prüfen Sie, ob der zurückgegebene Aussteller dasselbe Schema, denselben Hostnamen, denselben Pfad und denselben Realm-Namen verwendet, die Sie in oCIS konfigurieren. OpenID Connect validiert die Ausstelleridentität exakt; eine Abweichung des Reverse-Proxy-Hostnamens oder ein zusätzlicher Schrägstrich kann die Anmeldung verhindern.

2. Registrieren Sie einen OIDC-Client für ownCloud Web

Ein Client ist die Anwendungsregistrierung, die Keycloak verwendet, um zu entscheiden, welcher Dienst eine Anmeldung anfordern kann. Erstellen oder passen Sie einen OpenID Connect-Client im für oCIS verwendeten Bereich an. Verwenden Sie eine Client-ID wie z. B. „openid-connect“ weboder einen benutzerdefinierten Wert und stellen Sie sicher, dass dieser mit dem WEB_OIDC_CLIENT_IDWert in oCIS übereinstimmt. Das offizielle ownCloud-Beispiel verwendet „openid-connect“ webals Standardwert.

Verwenden Sie für einen browserbasierten Client den Standard-Autorisierungscode-Ablauf und eine öffentliche Client-Konfiguration, die mit dem offiziellen Beispielbereich übereinstimmt. Geben Sie die exakten HTTPS-Weiterleitungs- und Post-Logout-Weiterleitungsmuster an, die für Ihre Bereitstellung erforderlich sind. Ein eng gefasstes Hostnamenmuster https://cloud.example.com/*ist einfacher zu prüfen als ein weit gefasstes Wildcard-Muster für alle Hosts. Fügen Sie nur die Web-Ursprünge hinzu, die Ihre Bereitstellung benötigt. Erstellen Sie kein Client-Geheimnis für einen öffentlichen Browser-Client und betten Sie es anschließend in die Frontend-Konfiguration ein.

3. Überprüfen Sie die Ansprüche und den Umfang.

OIDC-Claims sind Identitätsattribute, die in einem Token gespeichert oder vom User-Info-Endpunkt zurückgegeben werden. Wählen Sie mindestens den Benutzernamen-Claim sorgfältig aus. Der ownCloud-Proxy verwendet standardmäßig preferred_usernamedie Benutzerauflösung, und das Keycloak-Beispiel konfiguriert den Webclient mit Standardprofil- und E-Mail-Bereichen. Stellen Sie sicher, dass Ihr Realm die verwendeten Claims tatsächlich zurückgibt; die Verfügbarkeit von Claims hängt von Client-Bereichen und Protokollmappern ab.

Bei bestehenden Konten muss der konfigurierte Anspruch dem entsprechenden stabilen ownCloud-Benutzerattribut zugeordnet werden. Ein geänderter Benutzername oder eine geänderte E-Mail-Adresse können zu Problemen bei der Kontozuordnung führen, wenn Sie diese als permanenten Identifikator verwenden. Der subAnspruch ist pro Identitätsanbieter garantiert eindeutig und stabil, stimmt aber möglicherweise nicht mit einem bereits vorhandenen Benutzernamen überein. Testen Sie die Kontozuordnung mit einem Nicht-Administrator-Konto, bevor Sie den Zugriff für alle Benutzer freigeben.

4. Unendliche Skala auf den Schlüsselmantel richten

Legen Sie die folgenden Werte in der Umgebung für die oCIS-Bereitstellung fest. Das Beispiel geht von HTTPS und einem Keycloak-Realm unter aus /realms/team. Verwenden Sie Ihre eigenen URLs. Dieser YAML-ähnliche Block dient nur der Veranschaulichung; Docker Compose, Kubernetes, systemd und andere Bereitstellungsmethoden verwenden unterschiedliche Umgebungsvariablen.

OCIS_URL: https://cloud.example.com
OCIS_OIDC_ISSUER: https://sso.example.com/realms/team
PROXY_OIDC_REWRITE_WELLKNOWN: "true"
WEB_OIDC_CLIENT_ID: web
PROXY_USER_OIDC_CLAIM: preferred_username
OCIS_EXCLUDE_RUN_SERVICES: idp

OCIS_OIDC_ISSUERWählt den externen Identitätsanbieter aus. PROXY_OIDC_REWRITE_WELLKNOWN=trueVeranlasst den Proxy, den OpenID Connect-Discovery-Endpunkt auf den konfigurierten Aussteller umzuschreiben; ownCloud dokumentiert dies als notwendig, damit Desktop- und Mobilclients den Anbieter ermitteln können. WEB_OIDC_CLIENT_IDMuss mit dem Keycloak-Client übereinstimmen. Der Ausschluss idpfolgt dem Keycloak-Beispiel von ownCloud, sodass der eingebettete Anbieter nicht als aktiver Anmeldeanbieter gestartet wird.

Soll oCIS beim ersten erfolgreichen Login Konten erstellen, PROXY_AUTOPROVISION_ACCOUNTS=truekonfigurieren Sie den Graph-Dienst mit einem schreibfähigen Benutzer-Backend. Weisen Sie PROXY_USER_OIDC_CLAIMdem PROXY_AUTOPROVISION_CLAIM_USERNAMEBenutzernamen-Attribut denselben Anspruch zu; Informationen PROXY_USER_CS3_CLAIM=usernamezu diesem Ablauf finden Sie in der ownCloud-Dokumentation. Die automatische Bereitstellung ist optional und sollte separat von der Authentifizierung getestet werden. Aktivieren Sie sie nur, wenn die eingehenden Ansprüche eindeutig sind und wie gewünscht zugeordnet wurden.

5. Erlauben Sie den Identitätsanbieter in der Inhaltssicherheitsrichtlinie.

Infinite Scale verwendet eine Content Security Policy (CSP), um zu steuern, welche externen Ursprünge der Webclient kontaktieren darf. Laut ownCloud-Dokumentation benötigt ein externer Identitätsanbieter wie Keycloak eine geeignete CSP-Definition. Wenn der Anmeldebutton angezeigt wird, der Browser die Anfrage jedoch blockiert, überprüfen Sie die Browserkonsole auf CSP-Fehler. Konfigurieren Sie die Richtlinie PROXY_CSP_CONFIG_FILE_LOCATIONund erlauben Sie nur den Keycloak-Ursprung und die für Ihre Bereitstellung erforderlichen Direktiven. Starten Sie den Proxy oder die Bereitstellung nach der Änderung der Datei neu. Beheben Sie Verbindungsprobleme nicht, indem Sie jeden Ursprung zulassen.

6. Starten Sie den Vorgang neu und überprüfen Sie ihn.

Wenden Sie die Umgebungsänderungen an und starten Sie die oCIS-Bereitstellung mit der gewohnten Verwaltungsmethode neu. Es gibt keinen universellen Neustartbefehl: Compose-Projekte, Kubernetes-Workloads und systemd-Dienste haben unterschiedliche Steuerungsmethoden. Überprüfen Sie anschließend jedes Glied in der Kette:

1. Öffnen Sie die Keycloak-Discovery-URL und vergewissern Sie sich, dass sie JSON mit den Werten issuer, authorization_endpoint, token_endpoint, und zurückgibt jwks_uri.
2. Öffnen Sie die ownCloud-Web-URL in einem privaten Browserfenster. Vergewissern Sie sich, dass der Browser zum erwarteten Keycloak-Realm weitergeleitet wird.
3. Melden Sie sich mit einem Testkonto an und überprüfen Sie, ob der Browser ohne Weiterleitungsschleife zum selben ownCloud-Hostnamen zurückkehrt.
4. Prüfen Sie, ob der beabsichtigte Benutzer – und nicht ein neu erstelltes Duplikat – in Infinite Scale angezeigt wird und nur auf die erwarteten Ressourcen zugreifen kann.
5. Testen Sie die Abmeldung und wiederholen Sie den Vorgang mit einem zweiten Konto. Falls Desktop- oder Mobilclients betroffen sind, testen Sie deren Erkennung und Anmeldung separat.

Häufige Fehler und ihre übliche Bedeutung

Produktionscheckliste

• Pin testete ownCloud- und Keycloak-Versionen, anstatt sich auf ein schwebendes latestTag zu verlassen.
• Verwenden Sie HTTPS sowohl für öffentliche Dienste als auch zur Beibehaltung der Zertifikatsprüfung. ownCloud dokumentiert die unsichere TLS-Überschreibung als ungeeignet für den Produktiveinsatz.
• Schützen Sie die Keycloak-Administratoranmeldeinformationen, sichern Sie die Keycloak-Datenbank und die Realm-Konfiguration und beschränken Sie den Keycloak-Administrationszugriff.
• Halten Sie Redirect-URIs und Web-Ursprünge auf die tatsächlichen ownCloud-Hostnamen beschränkt.
• Dokumentieren Sie den gewählten Identifikatoranspruch und die Folgen der Änderung von Benutzernamen, Realm-Namen, Aussteller-URLs oder Client-IDs.
• Testen Sie den Wiederherstellungszugriff, bevor Sie eine Produktionsinstanz umschalten, und behalten Sie einen geplanten Rollback der vorherigen Konfiguration bei.

Offizielle Referenzen

• ownCloud Infinite Scale 9.0 Proxy-Dienstkonfiguration
• ownCloud Keycloak Bereitstellungsbeispiel-Leitfaden
• Offizielle ownCloud ocis_keycloak-Bereitstellungsdateien
• Keycloak 26.8 Server-Administrationshandbuch
• ownCloud – Sicherheitsaspekte bei unbegrenzter Skalierung