Message Ops

A Global Admin configures providers under Admin → SSO providers. OIDC presets include Microsoft Entra ID, Okta, Auth0 and Generic OIDC; Generic SAML is also supported. Local password sign-in and multiple SSO providers can coexist.

Prepare the deployment

The operator must configure the public HTTPS WEB_BASE_URL, the full same-origin SSO_CALLBACK_BASE_URL (for example https://ops.example.com/api/v1/auth/sso/callback), and the SSO encryption key. Register that exact callback at the IdP. The default state lifetime is 600 seconds. Keep start and callback on the same hostname.

In production, metadata/discovery/JWKS/token/user-info URLs must use HTTPS and resolve to permitted public addresses. Loopback, private, link-local and other restricted ranges are rejected, as are redirects. A private CA does not exempt a private-address IdP from these endpoint restrictions. Obtain an approved reachable IdP endpoint rather than disabling TLS or switching to development mode.

Configure and test a provider

1. Keep a tested local administrator available during rollout. Open Create SSO Provider, choose the provider type and the sign-in display name.
2. For OIDC, supply the issuer/discovery information and client configuration. You can upload discovery JSON to populate endpoint fields; review the values before saving. Enable Authorization Code with PKCE at the IdP.
3. For SAML, supply the IdP entity ID, SSO URL and X.509 signing certificate. Metadata XML can populate these fields; DOCTYPE documents are rejected. Review the ACS URL and SP entity ID. When ACS is omitted the configured API callback is used.
4. Configure claim mappings for subject, email, name and groups as needed. Restrict allowed email domains. Select the exact provider IDs allowed on each existing user’s account; a domain filter alone does not grant access.
5. Save, complete MFA and use the provider test. Then perform a full sign-in in a separate browser session. A configuration test does not validate an actual IdP assertion, user access or role mapping.
6. Under Admin → Authentication, enable SSO and choose the default method. SSO requires an enabled provider. The final usable sign-in method cannot be disabled. If password credentials are disabled, enable and save them before replacing SSO with local sign-in.

Provider create/update/enable/disable/archive requires Global Admin and recent MFA. Platform Admin can inspect configuration and manage only grantable role mappings.

Identity and role mapping

First linking to an existing account requires verified email and explicit approval of that provider. Later sign-ins bind the provider ID, issuer and subject; a different subject cannot replace the established binding merely by presenting the same email. The IdP must supply stable subject and issuer claims. JIT provisioning is disabled by default; when enabled, newly provisioned users trust only their creating provider.

For SAML, the email attribute in a validated signed assertion is treated as verified. Ensure users cannot self-edit trusted email claims to another person’s address.

Group-to-role mappings target a specific provider and grant a role at Platform, Environment, Group or Queue scope, as allowed by that role. Queue mappings require an environment, Message VPN and queue patterns. Mapping changes undergo the same permission and scope checks as direct grants. Adding a provider does not inherit another provider’s user approvals or mappings.

Each successful SSO sign-in reconciles that provider’s sourced assignments with the current claims: matching enabled mappings grant access and grants from mappings that no longer match are removed. A valid empty group claim removes that provider’s mapped grants; a missing or malformed claim rejects sign-in when enabled mappings require groups. External IdP membership changes are learned at the next successful sign-in, not through continuous polling.

Disabling, re-scoping, changing the role/provider/group/patterns of, or deleting a mapping revokes its sourced grants and invalidates affected sessions immediately. Priority-only edits preserve grants. Disabling or archiving a provider removes its sourced grants and provider-issued sessions; re-enabling restores eligible grants only at the next successful sign-in. For immediate offboarding, use the applicable platform account/provider/mapping controls rather than waiting for an IdP change to be observed. Revocation does not undo a broker action already in progress.

Sourced grants are read-only in user edits: change their mapping or IdP membership. Manual grants and valid legacy grants without SSO provenance remain independent and need explicit review during offboarding. Do not remove legitimate manual grants merely because they resemble a mapping.

Mapped assignments authorize only sessions signed in through their source provider. Another provider’s session receives its own mapped grants plus manual grants. Local-password sessions and personal API tokens use manual assignments only. Keep intentional manual administrative access for the local recovery account and test each intended sign-in method.

SAML requirements

At least assertion signing or response signing must remain enabled. Use RSA-SHA256 or RSA-SHA512 signatures with SHA-256 or SHA-512 reference digests. SHA-1 is rejected even inside an otherwise acceptable signed response. Encrypted assertions are unsupported. The release does not provide an SP private-signing-key field, so do not rely on signed authentication requests.

Certificates may be pasted as PEM or base64 bodies. Test a complete sign-in after changing the certificate or signing algorithms; the provider test cannot observe the signatures the IdP will send.

Browser sessions and rotation

Production sessions use the Secure, HttpOnly __Host-message_ops_session cookie. SSO browser proof uses __Secure-message_ops_sso_binding, scoped to the callback path. OIDC uses SameSite=Lax and SAML uses SameSite=None. Both need HTTPS. Starting another attempt replaces the previous browser binding; restart sign-in if state expires or a callback is rejected.

Replace client secrets or certificates in the provider form and verify a complete sign-in before retiring the old IdP credential. Deployment encryption-key rotation is separate; follow Security and Secret Rotation.

Troubleshooting