OIDC / BYO-OIDC SSO konfigurieren

SupaCloud bietet zwei unabhängige SSO-Pfade (ADR 0031):

• Instance OIDC — der Betreiber konfiguriert einen gemeinsamen IdP über Umgebungsvariablen. Erfordert die Enterprise-Edition.
• BYO-OIDC — ein Organisationsinhaber konfiguriert seinen eigenen IdP in der SupaCloud-Oberfläche. Erfordert das Entitlement sso_oidc_byo im Plan der Organisation.

Beide Pfade verwenden denselben E-Mail-basierten Discovery-Flow beim Login. Sie können auf derselben Instanz gleichzeitig aktiv sein.

Hinweis

Proxy-Modus-SSO (AUTH_PROVIDER=authelia_proxy oder oidc_proxy) ist eine separate Deployment-Topologie für Betreiber, die einen vertrauenswürdigen vorgelagerten Reverse Proxy vor SupaCloud schalten. Die Konfiguration erfolgt ausschließlich über Umgebungsvariablen und ist nicht entitlement-gesperrt. Lies auth-authelia.md, wenn das dein Anwendungsfall ist.

---

Teil A — Instance OIDC (Enterprise, Self-Hosting)

Voraussetzungen

• Enterprise-Edition-Lizenz aktiv (siehe Edition-Lizenz anwenden).
• Ein OIDC-konformer IdP (Keycloak, Okta, Entra, Google Workspace usw.) mit einem vertraulichen Client, den du konfigurieren kannst.
• Die Redirect-URI, die du registrieren wirst: https://<your-domain>/api/auth/oidc/callback.

Schritte

1. Einen Client in deinem IdP registrieren.

   Setze die erlaubte Redirect-URI auf https://<your-domain>/api/auth/oidc/callback. Notiere die Issuer URL, die Client ID und das Client Secret.

2. Die Umgebungsvariablen setzen.

   Variable	Pflicht	Hinweise
   AUTH_PROVIDER	Ja	Auf oidc setzen
   OIDC_ISSUER_URL	Ja	IdP-Discovery-URL (z. B. https://accounts.example.com)
   OIDC_CLIENT_ID	Ja	Client-ID aus deinem IdP
   OIDC_CLIENT_SECRET	Ja	Client-Secret; in der Produktion OpenBao/Vault verwenden
   OIDC_REDIRECT_URL	Empfohlen	Vollständige Redirect-URI, die beim IdP registriert ist
   OIDC_SCOPES	Optional	Leerzeichen-getrennt; Standard ist openid email profile
   OIDC_PKCE_ENABLED	Optional	true (Standard) oder false
   OIDC_TOKEN_AUTH_METHOD	Optional	basic (Standard) oder post

3. Den Server neu starten.

   Instance OIDC erscheint in der /config-Liste auth.methods nur dann, wenn die Edition zu enterprise aufgelöst wird. Ein falsch konfiguriertes oder fehlendes Edition-Secret führt stillschweigend dazu, dass es weggelassen wird — überprüfe dies mit dem Feature-Verfügbarkeits-Panel (/api/admin/feature-availability).

4. Den Login-Flow testen.

   Navigiere zu https://<your-domain>/login. Im E-Mail-Eingabeschritt sollte der OIDC-Button erscheinen. Führe den IdP-Roundtrip durch und bestätige, dass du in der App landest.

Automatische Weiterleitung bei einem einzigen IdP

Auf einer eigenständigen Enterprise-Instanz mit genau einem SSO-Realm leitet SupaCloud nicht authentifizierte Besucher direkt zum IdP weiter — das Login-Formular wird dabei vollständig übersprungen. Dies wird durch das Feld sso.auto_redirect in /config gesteuert, das beim Start von services::auth::sso_policy abgeleitet wird.

Überschreibe den Standard mit zwei Umgebungsvariablen:

Variable	Werte	Auswirkung
SUPACLOUD_SSO_AUTOREDIRECT	on / off	Automatische Weiterleitung unabhängig von der Realm-Anzahl oder Edition erzwingen oder deaktivieren
DEFAULT_SSO_ORG	Org-Slug	Eine bestimmte BYO-Organisation als Ziel der automatischen Weiterleitung festlegen

off hat stets Vorrang. Ein Besucher kann die vollständige Methodenauswahl jederzeit über /login?switch=1 erreichen.

---

Teil B — BYO-OIDC pro Organisation (SaaS)

Organisationsinhaber, deren Plan das Entitlement sso_oidc_byo enthält, können ihren eigenen IdP konfigurieren, ohne den Betreiber einzubeziehen.

Voraussetzungen

• Rolle als Organisationsinhaber oder -administrator.
• Ein Plan, der sso_oidc_byo gewährt (Enterprise-Plan oder ein Workspace mit diesem Entitlement).
• Ein OIDC-konformer IdP mit einem vertraulichen Client.
• DNS-Schreibzugriff, um die E-Mail-Domain(s) der Organisation zu beanspruchen.

Schritte

1. Organisationseinstellungen → SSO öffnen.

   Navigiere zu Einstellungen → Organisation → SSO / OIDC. Wenn der Abschnitt anstelle des Konfigurationsformulars einen Upgrade-Hinweis anzeigt (ein Banner ‘auf einem höheren Plan verfügbar’ mit einem Upgrade-CTA und einer unscharfen Vorschau), enthält dein aktueller Plan kein sso_oidc_byo.

2. Die IdP-Konfiguration eingeben.

   Feld	Hinweise
   Issuer URL	IdP-Discovery-Endpunkt
   Client ID	Aus deinem IdP
   Client Secret	Nur schreiben — wird nach dem Speichern nicht mehr angezeigt
   PKCE	Standardmäßig aktiviert; nur deaktivieren, wenn der IdP es nicht unterstützt
   Scopes	Standard openid email profile

   Speichere die Konfiguration. Der Server speichert das Client-Secret verschlüsselt mit dem instanzweiten Credential-Verschlüsselungsschlüssel.

3. E-Mail-Domains registrieren und verifizieren.

   Füge unter Domains jede Domain hinzu, deren Benutzer zu diesem IdP geleitet werden sollen (z. B. example.com). Für jede Domain:

   a. SupaCloud generiert einen Verifizierungstoken und zeigt den erforderlichen DNS-TXT-Eintrag:

   supacloud-domain-verification=<token>

   b. Veröffentliche diesen TXT-Eintrag am Root der Domain (oder @). c. Klicke auf Verifizieren in der Oberfläche (oder rufe POST /api/v1/org/oidc/domains/{id}/verify auf). SupaCloud führt eine DNS-Abfrage durch und markiert die Domain bei Erfolg als verifiziert.

   Achtung

   Domain-Beanspruchungen sind unter den verifizierten Einträgen global eindeutig. Wenn eine andere Organisation eine Domain, die du benötigst, bereits verifiziert hat, wende dich an den Support.

4. Die Redirect-URI in deinem IdP setzen.

   Registriere https://<your-domain>/api/auth/oidc/byo/<org_slug>/callback als erlaubte Redirect-URI. Der <org_slug> ist der URL-Slug deiner Organisation.

5. Den Login-Flow testen.

   Gib auf der gemeinsamen Login-Seite eine E-Mail-Adresse an einer verifizierten Domain ein. SupaCloud erkennt die Organisation über eine nicht-aufzählende E-Mail-Domain-Suche und leitet zum BYO-IdP weiter. Nach einem erfolgreichen IdP-Roundtrip landet der Benutzer in der App.

Cookie für gespeicherten Realm und lesezeichenfähige Einstiegs-URL

Nach einem erfolgreichen BYO-Callback setzt SupaCloud ein sc_sso_org-Cookie (HttpOnly, 90-Tage-Hinweis). Beim nächsten Besuch liest das SSR-Login-Gate das Cookie und gibt direkt einen 307 zum IdP aus — null Klicks für wiederkehrende Benutzer.

Teile oder bookmarke https://<your-domain>/sso/<org_slug> als direkte IdP-Einstiegs-URL (auch geeignet als IdP-Portal-App-Kachel).

Um den gespeicherten Realm zurückzusetzen (gemeinsamer Browser, veraltete Konfiguration), besuche /api/auth/sso/forget oder verwende /login?switch=1.

---

Management-API (IaC / skriptbasierte Provisionierung)

BYO-OIDC kann deklarativ über die Management-API (Org-Inhaber-Token) verwaltet werden:

Methode	Pfad	Auswirkung
GET	/api/management/v1/organizations/{org_id}/oidc	Aktuelle Konfiguration lesen
PUT	/api/management/v1/organizations/{org_id}/oidc	IdP-Konfiguration anlegen oder aktualisieren
DELETE	/api/management/v1/organizations/{org_id}/oidc	Konfiguration entfernen

Anfrage- und Antwortschemata findest du in der Management-API-Referenz.

---

Fehlerbehebung

Der OIDC-Button erscheint nicht auf der Login-Seite. Bestätige, dass AUTH_PROVIDER=oidc gesetzt ist und die Edition zu enterprise aufgelöst wird (/api/admin/feature-availability). Prüfe, ob OIDC_ISSUER_URL, OIDC_CLIENT_ID und OIDC_CLIENT_SECRET alle gesetzt und nicht leer sind.

Das BYO-OIDC-Konfigurationsformular wird in den Organisationseinstellungen durch einen Upgrade-Hinweis ersetzt. Das Entitlement sso_oidc_byo ist im aktiven Plan nicht gewährt. Upgrade das Abonnement der Organisation oder wende dich an den Instanzbetreiber.

Die Domain-Verifizierung schlägt fehl. Die DNS-Übertragung kann mehrere Minuten dauern. Überprüfe den TXT-Eintrag mit dig TXT <domain> und versuche es erneut. Der Eintrag muss am Domain-Apex veröffentlicht sein.

Automatische Weiterleitung läuft nach einem IdP-Fehler in einer Schleife. Navigiere zu /login?switch=1, um die vollständige Methodenauswahl zu erreichen und das sc_sso_org-Cookie zu löschen. Analysiere dann den IdP-Callback-Fehler in den Server-Logs.

Der Login springt zur Login-Seite zurück und die Logs erwähnen eine nicht verifizierte E-Mail. SupaCloud akzeptiert nur eine E-Mail-Adresse, die der IdP als verifiziert markiert — der email_verified-Claim (im ID-Token oder in einer passenden userinfo-Antwort) muss true sein. Konfiguriere deinen IdP so, dass er email_verified für den email-Scope liefert; ein IdP, der den Claim weglässt oder false sendet, wird abgelehnt. Das verhindert, dass ein falsch konfigurierter oder bösartiger IdP einen Nutzer als Adresse authentifiziert, die er nicht kontrolliert. Sowohl Instanz-OIDC als auch BYO-OIDC erzwingen dies.