SSO, permissions and session logout

Shared identity with application-owned authorization#

Matrix applications can share an identity provider and SSO session while retaining separate Web clients, API audiences, cookies and permissions. Portal links contain no tokens. A destination application starts its own OpenID Connect flow and can reuse an existing provider session, subject to the installation's identity policy.

Authentication establishes who is calling. Application authorization establishes what that caller may do. Portal launch eligibility, access to personal preferences and permission to perform a business mutation are distinct decisions. Each API must validate its own access-token audience and enforce relevant resource, record and tenant rules.

Establish the identity contract#

Keep provisioning credentials in a controlled registration job. Web receives its own confidential-client credential; APIs and auxiliary services receive only the identities required for their roles. A directory reader or migration login is not a general-purpose application credential.

For a Matrix consumer, retain the shared AddMatrixWeb and AddMatrixApi composition. The Infrastructure integration recipe also contains examples for ordinary ASP.NET Core applications, but those examples should not be registered as a second authentication pipeline on top of Matrix.

Current sign-out contract#

Matrix alpha.48 changed the standard Shell menu to Sign out in every role. The menu submits an antiforgery-protected POST to the application's own configured LogoutPath. Coordinator and Participant handlers authenticate their named cookie, require its saved ID token and usable HTTPS provider metadata, prepare normal OIDC logout, then revoke the local session. A valid Participant POST executes logout; it does not return the older MXLOGOUT006 rejection. GET never performs logout.

Adopt a coherent alpha.48 runtime and matching consumer kit before expecting this behavior. Alpha.46/47 retain their published Portal-confirmation journey. Application package adoption is a separate step from platform publication.

The following participant configuration remains accepted. CentralUrl is retained and validated for compatibility and custom navigation; it no longer selects the standard menu action. Replace these example origins with reviewed installation values and retain the application's existing issuer, credentials and API configuration.

{
  "Authentication": {
    "CoordinatedLogout": { "Enabled": true },
    "Logout": {
      "Mode": "Participant",
      "PublicOrigin": "https://application.example.test",
      "CentralUrl": "https://portal.example.test/logout"
    }
  },
  "Matrix": {
    "Shell": {
      "ProjectsUrl": "https://portal.example.test/applications"
    }
  }
}

Projects navigation is independent of logout policy. Keep the Shell's SignOutPath aligned with the local logout endpoint, conventionally /authentication/logout. Direct sign-out needs no Portal cookie, Portal-specific endpoint, cross-origin form, token exchange or new identity callback registration.

Successful initiating logout returns through the existing OIDC callback to the configured LoginPath, starting the normal login screen. Caller-supplied return destinations are ignored. Provider callback errors show a sanitized failure without automatically logging in. Other tabs ended by signed backchannel notifications keep their clean signed-out document and do not automatically start login.

These failures preserve the session. A later provider/network failure can leave provider logout unfinished after local revocation; it must remain a failure/retry outcome.

The Coordinator still offers an optional explicit confirmation entry for custom navigation. The standard menu does not visit it. Its identity-only flow must not require Projects/catalog privileges. Default AddMatrixWeb pairs named-cookie logout and callback failure handling in every role. Custom OIDC hosts must apply UseMatrixLogoutEntry with matching endpoint options for both enrolled roles.

Session limits and acceptance#

The documented coordinator and refresh model has process-local limits. Sharing Data Protection keys alone does not establish distributed coordination or high availability. Existing API bearer tokens retain their normal lifetime; central sign-out is not an instantaneous all-device revocation guarantee.

Test sign-in and direct API denial, then local menu POSTs in both enrolled roles, missing/invalid antiforgery input, missing cookie or ID token, unavailable metadata and provider callback failure. Verify initiating completion reaches the configured login route while backchannel-ended tabs remain signed out. Check isolation of another session for the same user and identity access without Projects privileges.

Validate proxy trust before testing OIDC: the application must recognize the exact trusted reverse proxy and canonical host, with forwarded-header handling before authentication. Untrusted forwarded values can otherwise change generated callback origins.

External-provider federation is installation-owned work. A shared identity architecture does not automatically enroll every legacy application or configure external federation. Retain those mappings and their acceptance evidence separately from Portal's directory settings.