Workspace als Identity Provider nutzen

Nutzen Sie den Workspace Identity Provider für Single Sign-on (SSO), wenn Anwendungen ihre Benutzer über Workspace anmelden und zentrale Freischaltungen aus Workspace beziehen sollen. Der OIDC Enterprise Core stellt Discovery, JWKS, Authorization Code mit PKCE, Token, UserInfo, Feature-Scopes, Entitlements und Backchannel Logout für OIDC-basierte Anwendungen wie Matrix, Forgejo und spätere Dienste bereit.

Der Identity Provider ist nicht dasselbe wie Provider-Verbindungen. Provider- Verbindungen verbinden Workspace als Client mit externen Diensten, zum Beispiel Google Search Console. Der Identity Provider arbeitet in die andere Richtung: Externe Anwendungen vertrauen Workspace als Aussteller für Identität, Sitzungszustand und Freischaltungen.

Voraussetzungen

Für die Anmeldung an Workspace über einen anderen Identity Provider gilt ein separater Vertrag: Anmeldung über einen zentralen Identity Provider. Die dortige Capability wird unabhängig von identity_provider.sso freigeschaltet.

Prüfen Sie diese Punkte, bevor Sie eine Anwendung anbinden:

OIDC Discovery

Geben Sie angebundenen Anwendungen diese öffentlichen Endpunkte:

Standardmäßig erzeugt Workspace den Issuer aus server.publicURL, dem OIDC-Pfad und der kanonischen Tenant-ID. Ein Tenant kann stattdessen seine aktive, verifizierte Backend-Domain als Issuer-Origin verwenden. Die Tenant-ID bleibt Bestandteil des Issuers. Freie Host- oder X-Forwarded-*-Header ändern die Auswahl nicht.

Eigene Issuer-Domain sicher aktivieren

Öffnen Sie in der System-Integration Identity Provider den Bereich OIDC-Issuer. Die Oberfläche zeigt den aktuellen Issuer und eine verfügbare verifizierte Workspace-Domain. Vor der Aktivierung müssen alle Relying Parties auf den neuen exakten Issuer vorbereitet sein. Der Wechsel widerruft aktive OIDC-Sitzungen und Access Tokens, entwertet offene Authorization Codes und bricht laufende Anmeldeinteraktionen ab.

In einer Managed-Cloud-Installation ist die Aktivierung erst möglich, wenn Workspace die Edge-Publikation samt Routing und TLS als betriebsbereit beobachtet hat. Bei einer selbst betriebenen Installation verantwortet der Betreiber DNS, TLS und Routing und muss diese Voraussetzungen vor der Aktivierung selbst prüfen. Kann Workspace den hinterlegten Betriebsmodus nicht zuverlässig lesen, bleibt die Aktivierung gesperrt. Prüfen Sie in diesem Fall zuerst die globale Domain-Publikationskonfiguration.

Einen Aliasbetrieb gibt es nicht. Workspace gibt neue Protokollartefakte nur noch unter dem neuen Issuer aus. Discovery, ID Token, Access Token, UserInfo und Authorization Response müssen danach denselben Wert verwenden. Externe Konten können sich ändern, weil OIDC (issuer, subject) als Identität behandelt. Führen Sie eine notwendige Kontenmigration in der Relying Party bewusst durch; Workspace führt Konten nicht anhand der E-Mail-Adresse zusammen.

Eine aktive Issuer-Domain kann nicht widerrufen oder gelöscht werden. Legen Sie den benutzerdefinierten Issuer erst still, wenn alle Relying Parties auf den als Issuer nach Stilllegung angezeigten Issuer migriert oder außer Betrieb genommen wurden. Geben Sie die Domain erst anschließend frei. Ein späterer Domaininhaber könnte sonst unter demselben alten Issuer eigene Discovery-Daten und Schlüssel veröffentlichen; Workspace kann das nach Verlust der Domainkontrolle nicht verhindern. Fällt eine aktive Issuer-Domain aus oder verliert ihren Verifikationsstatus, erfolgt kein stiller Fallback auf server.publicURL. Die OIDC-Endpunkte bleiben dann gesperrt. Die Administrationsoberfläche zeigt den Grund weiterhin an und lässt den benutzerdefinierten Issuer stilllegen, damit der Tenant kontrolliert auf den angezeigten Standard-Issuer zurückkehren kann. Das gilt auch dann, wenn Workspace den Betriebsmodus vorübergehend nicht lesen kann.

Die früheren globalen OIDC-Endpunkte antworten mit 410 Gone. Clients müssen auf den tenantgebundenen Issuer umgestellt werden. Ein tenant_id-Parameter im Authorize-Request wird nicht mehr akzeptiert.

OIDC-Anmeldung ausführen

Konfigurieren Sie die Anwendung für den Authorization-Code-Flow mit PKCE. Der Authorize-Request muss response_type=code, client_id, redirect_uri, scope mit openid, code_challenge und code_challenge_method=S256 enthalten. Der Tenant ist bereits Bestandteil des Issuers und des Endpunkts.

Fehlt eine Workspace-Sitzung, startet Workspace eine interaktive Anmeldung. Danach prüft Workspace bei Bedarf Kontoauswahl und Einwilligung und setzt den ursprünglichen OIDC-Request fort. prompt=none öffnet keine Oberfläche und liefert stattdessen den passenden OIDC-Fehler zurück. Unterstützt werden prompt=login, select_account, consent, max_age sowie die Response-Modi query und form_post. Der Token-Endpunkt löst Codes genau einmal gegen Tenant-Issuer, Client-Secret, Redirect-URI und PKCE-Verifier ein. UserInfo akzeptiert gültige Bearer Access Tokens.

Fehlerhafte interaktive Anfragen werden erst nach erfolgreicher Prüfung von Client und Redirect-URI und nach der Anmeldung an die Anwendung zurückgegeben. So kann ein anonymer Aufruf den Workspace-Login nicht als offenen Redirector verwenden. prompt=none bleibt davon ausgenommen und liefert den gebundenen Fehler ohne Oberfläche zurück. Geht die Sitzung während der Interaktion verloren, führt Workspace denselben opaken Handle zurück zur Anmeldung.

Wenn ein Benutzer die Anmeldung oder den angeforderten Zugriff ausdrücklich abbricht, sendet Workspace access_denied, den ursprünglichen state und den Issuer an die Anwendung zurück. Das gilt auch vor der Anmeldung, aber nur für den weiterhin aktiven Client und seine erneut geprüfte, exakt registrierte Redirect-URI. Ist die Anfrage abgelaufen, bereits verwendet oder nicht mehr sicher an diese Anwendung gebunden, bleibt Workspace auf der lokalen Fehlerseite. Starten Sie die Anmeldung dann erneut aus der Anwendung.

Die Interaktionskennung liegt nur im URL-Fragment der Login-Seite, wird dort sofort entfernt, serverseitig verschlüsselt gespeichert und nach 15 Minuten ungültig. Sie darf nicht in Logs, Support-Tickets oder Screenshots übernommen werden. Ein vollständiger Reload der Login-Seite verwirft die Kennung bewusst; starten Sie die Anmeldung in diesem Fall erneut aus der angebundenen Anwendung.

Anwendung registrieren

Registrieren Sie eine Anwendung in der System-Integration Identity Provider. Die Oberfläche zeigt die SSO-Readiness, Application Profiles, OIDC-Clients, die Secret-Rotation, E-Mail-Domains, Domain-Policies, Feature-Scopes, Entitlements, OIDC-Sessions und Backchannel-Logout-Deliveries. Für automatisierte Einrichtung oder noch nicht oberflächengeführte Bereiche stehen dieselben Admin-Endpunkte zur Verfügung:

Speichern Sie nur HTTPS-Redirect-URIs ohne Fragment und ohne Userinfo sowie eine HTTPS-Backchannel-Logout-URI ohne Fragment und ohne Userinfo. Tragen Sie Feature-Scopes und Entitlements so ein, dass sie fachlich zur Anwendung passen. Anwendungen wie Matrix oder Forgejo können später aus diesen Scopes ableiten, welche Funktionen ein Benutzer in der Anwendung nutzen darf. Begrenzen Sie die erlaubten Feature-Scopes am Client, wenn eine Anwendung nur einen Teil der aktiven und gewährten Scopes akzeptieren soll. Wählen Sie pro Client EdDSA oder RS256. Für RS256 muss zuvor ein aktiver RSA-Schlüssel bereitgestellt worden sein. Prüfen und rotieren Sie den Bestand mit dem lokalen Offline-Werkzeug; verändernde Befehle bleiben ohne --apply ein Dry-Run:

numin identity-provider signing-key status --json
numin identity-provider signing-key prepare
numin identity-provider signing-key prepare --apply
numin identity-provider signing-key activate --kid <kid>
numin identity-provider signing-key activate --kid <kid> --apply
numin identity-provider signing-key retire --kid <kid>
numin identity-provider signing-key retire --kid <kid> --apply

Ein neuer Schlüssel wird zunächst vorbereitet. Seine Aktivierung versetzt den bisher aktiven Schlüssel in die Drain-Phase. Erst nach deren Ende darf der alte Schlüssel stillgelegt und sein privates Material gelöscht werden. Der prepare-Dry-Run prüft die Root-Key-Domain. Bei activate werden Datensatz und Entschlüsselbarkeit des Schlüssel-Envelopes geprüft; retire prüft Zustand und Drain-Frist. Keiner dieser Checks kann feststellen, ob alle Knoten dasselbe Root-Key-Bundle und denselben Release-Stand verwenden. Diese Flottenkonvergenz muss der Operator vor Aktivierung und Retirement getrennt bestätigen. Discovery und JWKS veröffentlichen beide unterstützten Algorithmen und aktive beziehungsweise auslaufende öffentliche Schlüssel.

Public Clients, Offline-Zugriff und zentrale Abmeldung

Den Clienttyp wählen

Wählen Sie bei der Registrierung den Typ passend zur Anwendung. Der Typ bleibt nach dem Anlegen fest; für einen anderen Typ legen Sie einen neuen Client an.

Alle Typen verwenden Authorization Code mit PKCE S256. Ein fehlendes Secret macht einen vertraulichen Client nicht zu einem Public Client. Native Apps nutzen für die Anmeldung den Browser. Zusätzlich zu HTTPS dürfen sie ein privates URI-Schema wie com.example.app:/oauth/callback oder eine Loopback-Adresse wie http://127.0.0.1/callback registrieren. Nur der Loopback-Port darf beim Anmelden variieren; bei der Code-Einlösung muss die vollständige tatsächlich verwendete Adresse übereinstimmen. Private Schemata und Loopback unterstützen ausschließlich den Antwortmodus query.

Für SPAs tragen Sie unter Erlaubte SPA-Origins die exakten HTTPS-Origins ein, etwa https://app.example. Pfade, Wildcards und ein abschließender Schrägstrich sind hier nicht zulässig. Token, UserInfo und Token-Widerruf erlauben Browserzugriffe nur für diese Origins. Die Anwendung verwendet dafür ihre Protokoll-Token und sendet keine Workspace-Cookies mit.

Offline-Zugriff freischalten

Aktivieren Sie Offline-Zugriff erlauben nur für Anwendungen, die ohne aktive Browser-Sitzung weiterarbeiten sollen. Die Anwendung fordert zusätzlich offline_access an. Workspace zeigt diesen Zugriff zur Einwilligung an; eine bereits erteilte gleichwertige Einwilligung kann weitergelten.

Die Anwendung erneuert Tokens mit grant_type=refresh_token am Token-Endpunkt. Jede erfolgreiche Einlösung liefert einen neuen Refresh-Token. Speichern Sie diesen anstelle des alten Tokens und führen Sie Refresh-Aufrufe nacheinander aus. Wird ein verbrauchter Token erneut verwendet, widerruft Workspace die gesamte zugehörige Token-Familie. Danach ist eine neue Anmeldung nötig.

Der Offline-Zugriff endet spätestens 30 Tage nach seiner Erteilung oder nach sieben Tagen ohne erfolgreiche Erneuerung. Eine Erneuerung verlängert die 30-Tage-Grenze nicht. Der natürliche Ablauf der Browser-Sitzung beendet den Offline-Zugriff nicht. Ausdrückliche Abmeldung und Zugriffswiderruf beenden ihn. Ein optionaler scope beim Refresh darf die bisherigen Scopes einschränken, aber nicht erweitern; openid bleibt erforderlich.

Aus einer Anwendung abmelden

Verwenden Sie den end_session_endpoint aus Discovery. Die Anwendung kann id_token_hint, client_id, post_logout_redirect_uri und state übergeben. Registrieren Sie erlaubte Rücksprünge separat unter Rücksprungadressen nach der Abmeldung. Workspace prüft diese Adressen exakt und zeigt vor der Abmeldung eine Bestätigung. Abbrechen lässt die Anmeldung bestehen.

Die Bestätigung beendet die zugeordnete Workspace-Anmeldung und deren App-Sitzungen und Offline-Zugriffe. Andere Browser oder Geräte bleiben angemeldet. Ob eine Fremdanwendung ihre lokale Sitzung sofort beendet, hängt von ihrer Backchannel-Logout-Unterstützung und der erfolgreichen Zustellung ab. Prüfen Sie das Verhalten für jede angebundene Anwendung.

Für einen gezielten Token-Widerruf verwendet die Anwendung den revocation_endpoint aus Discovery. Ein Refresh-Token widerruft seine Familie, ein Access Token nur diesen Token. Ein bereits unbekannter Token führt ebenfalls zu einer erfolgreichen Antwort und verrät keine fremden Zugriffe.

Einrichtung prüfen

Prüfen Sie zunächst die bisherige Anmeldung mit PKCE, Token-Einlösung und UserInfo. Testen Sie anschließend einen Refresh, eine Abmeldung mit Bestätigung und den erneuten Refresh-Versuch: Nach der Abmeldung muss er mit invalid_grant scheitern. Eine zweite, unabhängig gestartete Anmeldung muss weiter funktionieren. Prüfen Sie bei SPAs zusätzlich, dass eine nicht registrierte Origin keine Antwort lesen kann.

PeerTube anbinden

PeerTube wird als gewöhnlicher OIDC-Relying-Party-Client angebunden; Workspace enthält dafür keinen Sonderpfad. Die lokal geprüfte Kombination besteht aus PeerTube 8.2.4 und peertube-plugin-auth-openid-connect 1.2.0. Verwenden Sie den tenantgebundenen Issuer und registrieren Sie als Callback exakt https://<peertube-host>/plugins/auth-openid-connect/router/code-cb. Fordern Sie die Standard-Scopes openid email profile an. Die unveränderte Plugin-Konfiguration benötigt email für preferred_username und E-Mail-Adresse. Aktivieren Sie PKCE mit S256 und wählen Sie RS256; das Plugin sendet die Autorisierungsantwort mit response_mode=form_post.

Ein neuer Browser wird von Workspace zur Anmeldung geführt und danach zum PeerTube-Callback zurückgeleitet. Eine bereits angemeldete Person durchläuft abhängig von prompt, max_age und gespeicherter Einwilligung nur die noch erforderlichen Schritte. Falls PeerTube unmittelbar login_required erhält, prüfen Sie zuerst, ob es versehentlich prompt=none sendet oder noch den alten globalen Issuer verwendet. Endet PeerTube stattdessen mit externalAuthError=true, prüfen Sie Discovery, Token- und UserInfo-Endpunkt getrennt. Insbesondere darf ein vorgeschalteter Authentisierungsfilter den OIDC-Bearer am UserInfo-Endpunkt nicht als Workspace-Sitzungstoken behandeln.

Der lokale Docker-Browsertest deckt den anonymen Erstlogin, Consent, form_post, PKCE S256, RS256/JWKS, Code-Einlösung, UserInfo sowie die Anlage der PeerTube-Sitzung ab. Die übrigen Prompt-, Fehler-, Replay- und Logout-Verträge werden durch fokussierte Workspace-Vertragstests geprüft; dieser Nachweis ist keine Herstellerzertifizierung.

Nutzen Sie GET /api/v1/idp/application-profiles, um versionierte Workspace-Defaults für typische Anwendungen abzurufen. Der Profilkatalog enthält derzeit Matrix/Synapse, Matrix/Conduit und Forgejo. Er liefert empfohlene OIDC-Scopes, Redirect-URI-Hinweise, Claim-Mapping-Vorschläge, Feature-Scopes und App-seitige Konfigurationsschlüssel. Workspace legt damit keine externen Anwendungen an und speichert keine Secret-Werte in Client-Metadaten.

Für anwendungsspezifische Profile können Sie im Client externalSettings pflegen. Speichern Sie dort nur nicht geheime Werte oder Secret-Referenzen, zum Beispiel Matrix-Servername, Homeserver-URL, Web-Client-URL oder die ID eines verschlüsselten Secrets. Speichern Sie Secret-Werte selbst in der Secret-Ablage.

Konfigurieren Sie claimMapping, wenn eine Anwendung andere Claim-Namen erwartet. Workspace unterstützt Claim-Mapping V1 als typisierten Vertrag, nicht als freie Transformation:

Workspace lässt nicht zu, dass Mapping-Ziele JWT- oder OIDC-Standardclaims wie sub, iss, aud, exp, iat, sid, client_id oder scope überschreiben. Nutzen Sie für App-Kompatibilität stattdessen Alias-Claims wie groups oder permissions.

Der Authorization-Code-Flow akzeptiert nur bekannte OIDC-Scopes und aktive Feature-Scopes der jeweiligen Anwendung. openid ist verpflichtend. email schaltet email und preferred_username frei, profile schaltet name frei und groups schaltet den konfigurierten groupsClaim frei. Für jede Anmeldung muss ein aktives Entitlement für die Identity und die Anwendung existieren. Angeforderte Feature-Scopes müssen als aktive App-Scopes existieren, in einer optionalen Client-Allowlist enthalten sein und im aktiven Entitlement der Identity liegen. Workspace prüft diesen Vertrag vor der Code-Ausgabe und erneut beim Token-Exchange.

E-Mail-Domains und Domain-Policies verwalten

Nutzen Sie E-Mail-Domains, wenn Benutzer mit einer definierten Kundendomäne projektunabhängig Zugriff auf eine Anwendung erhalten sollen. Legen Sie die Domain in der Identity-Provider-Systemfläche an und starten Sie die DNS-Verifikation. Workspace erzeugt einen TXT-Namen und einen TXT-Wert. Tragen Sie den Wert im DNS der Domain ein und prüfen Sie danach den DNS-Nachweis in Workspace.

Eine Domain ist erst zugriffsrelevant, wenn sie aktiv ist und den Status verified hat. Aktivieren Sie Self Join nur, wenn Benutzer dieser Domain sich über den öffentlichen Domain-Join-Flow selbst registrieren dürfen. Der öffentliche Flow läuft immer im Tenant der aktuellen Site und erstellt die Tenant-Mitgliedschaft erst nach erfolgreicher E-Mail-Code-Bestätigung.

Verknüpfen Sie die verifizierte Domain anschließend mit einer Anwendung über eine Domain-Policy. Die Policy enthält Rollen und Feature-Scopes für alle Benutzer mit verifizierter E-Mail-Adresse dieser Domain. Die Feature-Scopes müssen weiterhin als aktive Scopes der Anwendung existieren.

Ein explizites Entitlement für eine Identity hat Vorrang vor der Domain-Policy. Ein aktives Entitlement setzt Rollen und Feature-Scopes individuell. Ein inaktives Entitlement sperrt den Zugriff auch dann, wenn die Domain-Policy passen würde.

Matrix/Conduit anbinden

Wählen Sie für Conduit das Application Profile matrix-conduit. Workspace modelliert diese Anbindung als anwendungsspezifischen Launch-Vertrag mit matrix_jwt, nicht als vollständiges Matrix-Provisioning.

Pflegen Sie im Client die externen Settings:

Der Launch-Endpunkt prüft den effektiven Zugriff aus Entitlement oder Domain-Policy und gibt für berechtigte Benutzer einen kurzlebigen m.login.token-kompatiblen Token zurück. Workspace verwaltet dabei die lokale Zuordnung zwischen Workspace-Identity und Matrix-Subject. Räume, Power-Level, Server-Moderation und vollständiges Remote-Provisioning bleiben ein separater Integrationsschritt.

Rotieren Sie für jeden OIDC-Client ein Client-Secret. Workspace zeigt das neue Secret nur unmittelbar nach der Rotation an und speichert anschließend nur einen Hash. Listen- und Detailantworten enthalten ausschließlich den Secret-Status. Prüfen Sie danach GET /api/v1/idp/readiness; die Antwort nennt fehlende Voraussetzungen als stabile Codes, zum Beispiel idp_sso_feature_disabled, idp_no_active_oidc_clients, idp_clients_missing_secrets, idp_clients_missing_redirect_uris, idp_duplicate_client_ids, idp_backchannel_clients_missing_logout_uri oder idp_signing_unavailable.

Feature-Scopes und Entitlements verwalten

Legen Sie zuerst die Feature-Scopes einer Anwendung in der Identity-Provider-Systemfläche an. Ein Scope ist ein stabiler technischer Wert wie rooms:moderate; labelKey und descriptionKey verweisen auf die spätere Anzeige in Anwendung oder Admin-Oberfläche. Setzen Sie isActive=false, wenn ein Scope nicht mehr vergeben werden soll. Workspace widerruft bestehende OIDC-Sessions und Access-Token-Handles für die Anwendung, wenn sicherheitsrelevante Client-, Entitlement- oder Feature-Scope-Änderungen den bestehenden Zugriff verändern.

Speichern Sie danach Entitlements für einzelne Workspace-Identitäten. Die Oberfläche verwendet dafür die stabile Identity-ID. Ein Entitlement enthält Rollen und Feature-Scopes für genau eine Anwendung und einen Tenant. Workspace akzeptiert nur Feature-Scopes, die für dieselbe Anwendung aktiv definiert sind. Der OIDC Authorization-Code-Flow projiziert nur angeforderte und gewährte Feature-Scopes als entitlements in ID Token, Access Token und UserInfo. Rollen werden als roles ausgegeben, wenn das Claim-Mapping sie aktiviert.

Backchannel Logout

Wenn eine Identity ihre Tenant-Mitgliedschaft verliert oder ein App-Zugriff widerrufen wird, widerruft Workspace aktive OIDC-Sessions und zugehörige Access-Token-Handles. Für Sessions mit aktivem Backchannel Logout merkt Workspace Backchannel-Logout-Deliveries vor. Die Auslieferung erfolgt automatisch durch den IdP-Logout-Dispatch-Worker. Die Admin-Oberfläche zeigt Sessions und Deliveries pro Client; für operative Nachläufe oder gezielte Prüfungen steht zusätzlich die geschützte Admin-Dispatch-API bereit:

Der Dispatch sendet pro Delivery ein signiertes logout_token als application/x-www-form-urlencoded HTTP-POST an die Backchannel-Logout-URI der Anwendung. Die Anwendung muss das Token gegen den JWKS-Endpunkt prüfen und die lokale Session mit der enthaltenen sid schließen.

Der Worker verarbeitet nur Tenants, bei denen identity_provider.sso aktiv ist. Fällige Deliveries werden vor dem HTTP-POST kurz geleast, damit parallele Worker dieselbe Delivery nicht doppelt senden. Fehlgeschlagene Versuche bleiben in der Outbox und werden über next_attempt_at erneut versucht; nach den vorgesehenen Versuchen landet die Delivery im Status failed.

Grenzen des OIDC Enterprise Core

Der Enterprise-Core-Schnitt enthält OIDC Discovery, JWKS, Authorization Code mit PKCE, Token, UserInfo, Backchannel Logout, Feature-Scopes, Entitlements, Session-/Delivery-Operability und eine Admin-Oberfläche für diese Kernflächen. Die oben beschriebenen Erweiterungen einschließlich Refresh-Tokens sind in Workspace 10.0.0 enthalten. Ein produktiver LDAPS-Server und Remote-Provisioning für Matrix oder Forgejo gehören ebenfalls nicht zum aktuellen Umfang. Planen Sie die App-seitige Einrichtung und Abnahme deshalb als nächsten Integrationsschritt auf diesem Kern.