SSO (WorkOS)

Rensei uses WorkOS to provide enterprise-grade Single Sign-On. Every authentication flow - password, OAuth/OIDC, and SAML - runs through WorkOS AuthKit, giving your identity team a single integration point for all supported providers.

How it works

When a user belongs to multiple WorkOS organizations, AuthKit surfaces an organization-selection step before returning the final token. The organizationId returned on every auth result tells Rensei which org session to establish.

Enabling an SSO connection

Create a WorkOS Connection

In the WorkOS Dashboard, navigate to Organizations → <your-org> → Single Sign-On and create a new connection. Record the Connection ID (format: conn_...).

Supported connection types: Google OAuth, Microsoft OAuth, GitHub OAuth, SAML, OIDC.

Enable SSO in Rensei

In Rensei, go to Settings → Security → SSO. Paste the Connection ID and provider name from WorkOS. Saving calls the platform's enableSso() helper, which persists enabled: true and emits a sso.connection_created audit event.

(Optional) Enforce SSO

Toggle Require SSO for all members. This sets enforced: true, which prevents password-based login for all workspace members. You cannot enforce SSO before a connection is active - the platform rejects the call with Cannot enforce SSO when SSO is not enabled.

Enforcing SSO before verifying that every existing member can authenticate through the new connection will lock them out. Test with a staging account first.

SSO configuration model

The platform stores a per-workspace SsoConfig object:

interface SsoConfig {
  enabled: boolean
  enforced: boolean
  connectionId: string | null   // WorkOS conn_... ID
  provider: string | null        // e.g. "GoogleOAuth", "SAML"
}

Changes to this object emit audit events of type sso.connection_created or sso.connection_removed, giving your audit trail a complete SSO history.

Organization-scoped connections

If you run multiple Rensei organizations, each organization has its own independent SSO configuration. The organizationId returned by WorkOS after authentication is used to resolve which Rensei organization to scope the session to. Multi-org users see the WorkOS organization-selection screen automatically.

Password reset

The platform delegates password reset to WorkOS. When a user requests a reset:

The platform calls workos.userManagement.createPasswordReset({ email }).
WorkOS sends a reset email directly to the user.
The user follows the link and calls the platform's resetPassword(token, newPassword) endpoint.

Custom reset URLs are not supported; the reset flow is fully WorkOS-hosted.

Admin portal (Directory Sync portal link)

Rensei exposes the WorkOS Admin Portal via Settings → Security → SSO → Open Admin Portal. The portal is scoped to either the sso or dsync intent depending on which tab you open. The portal link is a short-lived URL generated by generateAdminPortalLink(orgId, { intent, returnUrl }) - it expires after a few minutes.

Invitations

Invite new members from Settings → Members → Invite. Each invitation is sent through WorkOS (workos.userManagement.sendInvitation) and assigned a role at invite time. Accepted invitations create a WorkOS organization membership, which Rensei maps to its own orgMemberships table.

SCIM Directory Sync - automated user provisioning from your IdP
Members & RBAC - manage roles and teams after authentication
Audit Trail - every SSO event is recorded with hash-chain integrity

On this page