Single sign-on (SSO)

Orimora supports per-team single sign-on so each workspace can bring its own identity provider (IdP). Two protocols are available:

• OIDC (OpenID Connect) — Okta, Microsoft Entra ID, Google, Auth0, Keycloak, …
• SAML 2.0 — the same IdPs plus JumpCloud, OneLogin and other enterprise IdPs.

Process-wide environment providers (the OIDC_* and Google/Microsoft variables) still work as an instance-wide fallback.

How users sign in

On the login screen, a user enters their email and clicks Sign in with company SSO. Orimora maps the email’s domain to the team’s configured provider and redirects into the right flow. A team can also be reached directly via its slug:

• OIDC: /auth/oidc?team=<team-slug>
• SAML: /auth/saml/login?team=<team-slug>

A provider is only auto-discovered by email when its allowed domains are set (otherwise it would match every address); such a provider is reachable only via its team slug. New users are provisioned on first login (JIT) and bound to the SSO team; existing members are never reassigned.

Caution

Set APP_URL to your public https://… origin before enabling SSO — it is the basis for redirect URIs, the OIDC issuer check and the SAML entityID/ACS URL.

SSO and team-enforced MFA

If you turn on team-enforced MFA, an SSO login only satisfies the requirement when the IdP’s assertion proves it performed MFA — an OIDC amr of mfa (or a recognised second factor), or an MFA SAML AuthnContextClassRef (e.g. Microsoft Entra’s http://schemas.microsoft.com/claims/multipleauthn). A single-factor SSO login is recorded as not-yet-MFA and the member is still sent to enroll a local factor. To let SSO satisfy enforced MFA, configure your IdP to require and assert MFA.

Configure a provider

Open Settings → Identity (SSO) (requires the settings.team_edit capability).

OIDC

1. Add OIDC provider and fill in: display name, issuer URL, client ID, client secret, optional scope (default openid email profile).
2. Optionally set allowed email domains to enable email-based discovery and to restrict which domains may sign in.
3. Register the redirect URI \${APP_URL}/auth/oidc/callback in your IdP.
4. Enable the provider.

SAML 2.0

First, configure the instance-wide SP signing key (one pair for all teams):

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout sp-key.pem -out sp-cert.pem -days 1095 -subj "/CN=orimora-sp"
# set SAML_SP_PRIVATE_KEY and SAML_SP_CERT from these PEM files

Then in Settings → Identity (SSO) → Add SAML provider, fill in the IdP entity ID (Issuer), IdP SSO URL, the IdP signing certificate (PEM), NameID format, optional email attribute, and optional allowed domains.

Give your IdP these SP details:

• SP metadata: \${APP_URL}/auth/saml/metadata
• ACS (HTTP-POST): \${APP_URL}/auth/saml/acs
• Entity ID: \${APP_URL}/auth/saml/metadata

Security model

Each SAML assertion is validated against the provider’s pinned signing certificate. Orimora enforces: a valid XML signature (rejecting XML-signature- wrapping), the expected Issuer and Audience, the NotBefore/NotOnOrAfter lifetime (± clock skew), single-use InResponseTo correlation (replay defence), and a Success status — then applies the allowed-domain policy.

Note

The MVP supports SP-initiated SSO. IdP-initiated login and Single Logout (SLO) are not yet implemented (/auth/saml/slo returns 501); sign-out ends the local session only. A security review/pentest is recommended before enabling SAML in production.

Automated provisioning (SCIM 2.0)

SCIM lets your IdP create, update and deactivate users — and sync groups — automatically, so you don’t manage accounts by hand.

Set up

1. In Settings → Identity (SSO), under SCIM provisioning, click Create SCIM token. Copy the token immediately — it is shown only once.
2. In your IdP’s provisioning settings, set:
   • Tenant / Base URL: \${APP_URL}/scim/v2
   • Secret token: the token you just created
3. Map at least userName → email. Start provisioning.

Behaviour

• Users (/Users): create, read, replace (PUT), update (PATCH) and delete. Provisioning is idempotent — re-sending the same user (matched by externalId, then email) updates rather than duplicates.
• Deactivation is non-destructive. active=false (or a SCIM DELETE) suspends the user — their email is preserved so re-activation works. Orimora never hard-deletes via SCIM.
• New users join the Viewers group by default (least privilege); broader access comes from group membership.
• Groups (/Groups): create, patch members (add/remove/replace) and delete custom groups. The four system groups (Admins/Editors/Members/Viewers) are read-only over SCIM, and an IdP cannot remove the team’s last admin.
• Filtering supports eq, co, and sw on Users (eq/co on Groups); pagination uses startIndex/count; optimistic concurrency via ETag / If-Match.

Caution

A SCIM token grants full user/group provisioning for its team — store it like a password and revoke it the moment it is no longer needed. Tokens are hashed at rest and can be revoked anytime from the same screen. A pentest of the SCIM surface is recommended before production use.