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

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

OIDC Discovery

Geben Sie angebundenen Anwendungen diese öffentlichen Endpunkte:

Workspace erzeugt den Issuer aus server.publicURL, dem OIDC-Pfad und der kanonischen Tenant-ID. Setzen Sie diese Konfiguration in produktiven Deployments, damit Discovery, ID Token, Access Token und Logout Tokens denselben öffentlichen Issuer verwenden. Ohne server.publicURL nutzt Workspace nur den direkten Request-Host und den TLS-Zustand; freie X-Forwarded-*-Header ändern den Issuer nicht.

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.

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.

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. Refresh Tokens werden weiterhin nicht ausgegeben. 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.