Workspace als Identity Provider nutzen

Nutzen Sie den Workspace Identity Provider, 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 und hängt /api/v1/idp/oidc an. 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.

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. Wenn keine aktive Workspace-Session den Tenant vorgibt, geben Sie zusätzlich tenant_id mit.

Workspace nutzt nur bestehende Browser-Sessions. Wenn kein Benutzer angemeldet ist, leitet Workspace nach sicherer Client- und Redirect-URI-Prüfung mit error=login_required zur Anwendung zurück. Der Token-Endpunkt löst Codes genau einmal gegen Client-Secret, Redirect-URI und PKCE-Verifier ein. UserInfo akzeptiert gültige Bearer Access Tokens.

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.

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. Es gibt weiterhin keine Refresh Tokens, keine Consent-Oberfläche, keinen produktiven LDAPS-Server und kein Remote-Provisioning für Matrix oder Forgejo. Planen Sie die App-seitige Einrichtung und Abnahme deshalb als nächsten Integrationsschritt auf diesem Kern.