Use Workspace as an identity provider

Workspace can act as an OpenID Connect provider for applications that trust a Workspace tenant for sign-in, claims, entitlements, and session revocation. Each tenant has its own issuer:

https://workspace.example/api/v1/idp/oidc/tenants/{tenantId}

Use the issuer's discovery document at /.well-known/openid-configuration. It publishes the tenant-bound authorize, token, UserInfo, and JWKS endpoints. The former global OIDC endpoints return 410 Gone; do not send a tenant_id authorization parameter.

Clients use Authorization Code with PKCE S256. When no Workspace session is available, Workspace starts an interactive login and then continues account selection and consent as required. prompt=none never opens user interface and returns the applicable OIDC error. Workspace also supports prompt=login, select_account, consent, max_age, query, and form_post.

The browser interaction handle is short-lived, single-use, removed from the login URL immediately, and backed by encrypted server-side state. Do not copy it into logs or support material. A full reload of the login page deliberately discards the handle; restart sign-in from the relying party in that case. For an anonymous interactive request, Workspace returns request errors to a validated relying-party redirect only after authentication. This prevents the trusted login host from acting as an open redirector. prompt=none remains the non-interactive exception and returns its bound error without opening UI. If the session is lost during an interaction, Workspace returns the same opaque handle to sign-in.

Configure an exact HTTPS redirect URI, rotate a client secret, and choose EdDSA or RS256 per client. RS256 requires an active persisted RSA signing key prepared with numin identity-provider signing-key. Users can review and revoke stored application consent under Profile > Connected apps.

PeerTube example

Register PeerTube as a normal OIDC relying party. For the currently documented and locally verified combination, PeerTube 8.2.4 with peertube-plugin-auth-openid-connect 1.2.0, use the tenant issuer and register https://<peertube-host>/plugins/auth-openid-connect/router/code-cb exactly. Configure PKCE S256, openid email profile, and RS256. If an anonymous browser receives login_required immediately, check whether PeerTube sends prompt=none or still uses the former global issuer.

Workspace does not create PeerTube accounts or roles remotely. Provisioning and application-specific authorization remain separate integration concerns.

Prerequisites and client registration

Enable the identity_provider.sso feature for the tenant and configure server.publicURL with the public HTTPS Workspace URL. Register only exact HTTPS redirect URIs without user information or fragments. A client also needs an active entitlement for each identity and may restrict the feature scopes it accepts. The authorization and token endpoints revalidate the client, redirect URI, entitlement, scope, issuer, and PKCE binding.

The Identity Provider administration area exposes readiness, application profiles, OIDC clients, client-secret rotation, verified email domains, domain policies, feature scopes, entitlements, sessions, and logout deliveries. The corresponding API starts at /api/v1/idp; use GET /api/v1/idp/readiness before enabling a relying party. Client secrets are displayed only when they are rotated and are stored as hashes afterwards.

claimMapping version 1 can map roles, entitlements, tenant, groups, email, and profile data to application-specific claim names. It cannot overwrite standard JWT and OIDC claims such as sub, iss, aud, exp, iat, sid, client_id, or scope. The email scope releases email and preferred_username; profile releases name; groups releases the configured group claim.

RS256 key lifecycle

Use the version-bound offline administration tool. Mutating commands are dry runs until --apply is supplied:

text

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

Preparation creates staged, encrypted RSA-3072 signing material. Activating it moves the previous active key into its drain period. Retire that key only after the drain period and after independently confirming that all server nodes use the converged root-key bundle and current release. The prepare dry run checks the root-key domain, activate checks the staged database row and decryptable key envelope, and retire checks state and drain deadline. None of these checks can observe fleet convergence. Retirement removes the key's secret material. JWKS continues to publish the public parts required to validate tokens during the transition.

Cutover preflight and rollback

Before switching a relying party, require a successful readiness response and zero duplicate active OIDC client IDs (idp_duplicate_client_ids). Confirm the exact callback URI, tenant issuer, selected signing algorithm, PKCE support, scope mapping, and a tested administrator login path that does not depend on the new integration. Keep the old relying-party configuration available until interactive login, consent, token exchange, UserInfo, logout, and error returns have been checked. Rollback changes the relying party back to its previous issuer and client settings; it does not restore retired signing material.

Verified PeerTube contract

The local Docker browser test uses PeerTube 8.2.4 and peertube-plugin-auth-openid-connect 1.2.0. It verifies anonymous sign-in, consent, form_post, PKCE S256, RS256/JWKS, code redemption, UserInfo, and the resulting PeerTube session. The plugin uses preferred_username and email by default, so the email scope is needed unless those mappings are changed.

If PeerTube ends at externalAuthError=true, inspect discovery, token, and UserInfo separately. An authentication filter in front of Workspace must not consume the OIDC Bearer token at UserInfo as a Workspace session token. The remaining prompt, error, replay, and logout contracts are covered by focused Workspace contract tests; the local check is not a vendor certification.

Email-domain access and application scopes

Verified email domains can grant application access through a domain policy. The domain must be active and DNS-verified; an explicit identity entitlement overrides the domain policy and can also deny access. Requested application feature scopes must be active, allowed by the client, and granted to the identity. Workspace revokes affected sessions and access-token handles when a security-relevant client, entitlement, or scope change removes access.

Back-Channel Logout

Workspace records OIDC sessions and queues a signed Back-Channel Logout token when tenant membership or application access is revoked. The delivery worker uses the same tenant-bound issuer that was stored with the session. The relying party validates the token with tenant JWKS and closes the local session named by sid. Failed deliveries remain visible for controlled retries.

Application profiles and limits

Versioned application profiles provide non-secret configuration guidance for Matrix/Synapse, Matrix/Conduit, and Forgejo. Matrix/Conduit uses a separate matrix_jwt launch contract; it is not full Matrix provisioning. Store only non-secret settings or references in externalSettings.

The current provider does not issue refresh tokens and does not provide SCIM, LDAP, or remote account and role provisioning. Validate application-side account creation, authorization, and logout as a separate integration step.