Single sign-on (SSO)

Single sign-on (SSO) lets members authenticate through your organization's identity provider. Sim supports OpenID Connect (OIDC) and SAML 2.0, with multiple providers per organization.

SSO authenticates accounts. First-sign-in provisioning can add organization membership, but workspace access is granted separately. Use directory provisioning to manage members and group-based access from your directory.

Before you start

• On Sim Cloud, use an Enterprise organization and an organization owner or admin account.
• On self-hosted deployments, enable the SSO flags and create an organization.
• Verify the email domain before saving its provider.
• Choose a Provider ID before configuring the identity provider. It is globally unique across Sim organizations, appears in callback URLs, and cannot be changed after saving. Use an organization-specific ID such as acme-okta.

Configure a provider

Open Settings → Organization → Single sign-on. The page has these tabs:

On self-hosted deployments, Provisioning appears when SCIM is enabled. Switching tabs preserves an unsaved sign-in draft while you remain on this page. Select Save or Update to commit changes. The selected tab and provider are in the URL, so you can bookmark or share them.

Under Sign-in, select Add identity provider, or select an existing provider to view it. Use Domains to verify ownership first.

Choose a protocol

Use OIDC when your provider supports OpenID Connect, or SAML 2.0 for a SAML connection. The provider guides below cover Okta, Microsoft Entra ID, Google Workspace, and AD FS.

Enter the required fields

For OIDC, also enter Client ID and Client secret. Sim discovers authorization, token, UserInfo, and JWKS endpoints from {issuer}/.well-known/openid-configuration. Under Advanced options, you can set Scopes (default openid,profile,email) and override authorization, token, or JWKS endpoints if discovery does not supply usable values.

For SAML, also enter Entry point URL, the provider's SSO service URL, and Identity provider certificate, its Base64 X.509 certificate. Under Advanced options, you can configure Audience, Callback URL override, signed-assertion requirements, NameID format, and IdP metadata XML. Metadata does not replace the required certificate.

Attribute mapping lets either protocol override the email, name, and stable user-ID claim names. Leave a mapping blank to use the protocol default.

Register the callback URL

Copy Callback URL for OIDC or ACS URL (Reply URL) for SAML, then register it in your identity provider:

Sim Cloud uses www.sim.ai; self-hosted deployments use their public domain. Use your chosen Provider ID in both systems. For SAML, register the SP Entity ID as the provider's audience/Entity ID. If you set a Callback URL override, Sim's copyable ACS URL uses that override.

Provider guides

https://<your-sim-domain>/sso/launch/acme-okta

Save and verify sign-in

Select Save for a new provider. Sign out, select Sign in with SSO on your deployment's login page, and enter an email in the verified domain. Sim selects the domain's provider, redirects to it, and returns the authenticated account to Sim.

If multiple providers serve the domain, ordinary sign-in uses the one marked Primary. Other providers can be reached through their Test sign-in link.

An OIDC dashboard can use the saved provider's Initiate login URL. Sim starts that provider's sign-in without asking for an email when the domain is verified and the launch includes a matching issuer. An already signed-in account goes directly to Sim.

Membership and account linking

Under First sign-in → On first SSO sign-in, choose:

Neither mode grants workspace access. After sign-in, members enter a workspace they can access or see a no-access state until an administrator grants access. For directory-managed workspace grants, push a group through SCIM and map it to a workspace.

Pending invitations and existing external workspace access take precedence over automatic membership, preserving their intended roles and grants. External workspace members access a specific workspace without joining the organization or consuming its seats.

When a new SSO identity asserts the email of an existing Sim account, Sim links it automatically. The provider's verified domain authorizes that linking for OIDC and SAML without requiring an email_verified claim. Sim matches the asserted email; it does not resolve aliases or different user principal names to an existing address. Send the same email when switching providers to preserve the account and its access.

An active, entitled SCIM connection can override Automatic with Disable just-in-time provisioning. Existing members, including invited members, can still sign in. See Provisioning and SSO together.

Require single sign-on

In Sign-in, set Allowed sign-in methods to Single sign-on. This option becomes available when the organization has an identity provider on a verified domain.

• The requirement applies when a session is created. Turning it on leaves current sessions active; members meet it at their next sign-in. Use Settings → Organization → Security → Sign out all members to revoke current member sessions too.
• Members who try password, email-code, or social sign-in see a message directing them to the identity provider.
• Organization owners retain the deployment's other enabled sign-in methods for recovery. An owner who has only used SSO can set a password through Forgot password and turn off the requirement if the provider fails.
• The requirement stops enforcing if no sign-in provider remains on a verified domain, or the organization loses SSO entitlement. It can be switched back to other methods at any time.
• Desktop handoff from an already authenticated browser remains available because it derives from an admitted session.

Turning the requirement off permits the deployment's other configured sign-in methods again. Enabling an SSO provider alone does not disable them.

Offboard a member

Disabling an account in the identity provider stops future SSO authentication. SSO alone does not revoke current Sim sessions or other sign-in methods. Remove the member in Sim as part of offboarding, or use SCIM deactivation to suspend access. SCIM suspension stops sign-in and personal API keys while preserving ownership; shared workspace keys continue working.

Edit or replace a provider

Select a saved provider under Sign-in, then select Edit. Its Provider ID stays fixed. Select Update to save, or Discard to abandon edits.

Saved OIDC secrets appear masked, with a suffix when available. Replace enters a new secret; Keep saved cancels replacement. SCIM settings in Provisioning save immediately and have no page-level Save action.

Deleting a provider removes its sign-in path, while accounts and memberships remain. If another verified provider serves the same domain, it becomes primary when the deleted provider was primary. Otherwise accounts must use another allowed sign-in method until a provider serves the domain again.

Switching identity providers

Configure and test a new provider before switching a domain:

1. Add it with the same verified domain. The current provider remains Primary.
2. Open the new provider and copy Test sign-in link. Test accounts use that provider; ordinary sign-in still uses the current primary.
3. Confirm the new provider asserts the same account emails, then select Make primary. New sign-ins use it; existing sessions remain active.
4. Keep the old provider to switch back with Make primary, or delete it after verification.

Different domains can also use different providers, such as Okta for eng.acme.com and Entra for acme.com. SCIM remains organization-wide alongside these providers.

Self-hosted setup

For a deployment with billing disabled, enable SSO and its browser twin:

SSO_ENABLED=true
NEXT_PUBLIC_SSO_ENABLED=true

# Organization membership on first SSO sign-in
ORGANIZATIONS_ENABLED=true
NEXT_PUBLIC_ORGANIZATIONS_ENABLED=true

# Optional directory provisioning tab
SCIM_ENABLED=true
NEXT_PUBLIC_SCIM_ENABLED=true

The enterprise master pair also enables these features. See Self-hosted enterprise for organization setup.

SSO_TRUSTED_PROVIDER_IDS is an optional comma-separated list for non-SSO provider account linking. It does not authorize SSO linking; SSO trust comes from the provider's verified domain.

Restricted networks can use the server-only SSO_SKIP_DOMAIN_VERIFICATION=true setting. Add the domain and select Verify before saving SSO. See DNS requirements and bypass trust consequences.

Script-based registration

Deployment operators can register directly against the database from the repository root. Provide DATABASE_URL or POSTGRES_URL, an existing account's SSO_USER_EMAIL, and SSO_ORGANIZATION_ID to bind the provider to the organization. Without the organization ID, the provider is user-scoped and does not add organization membership at first sign-in.

OIDC example:

DATABASE_URL=... \
SSO_ENABLED=true \
NEXT_PUBLIC_APP_URL=https://sim.example.com \
SSO_PROVIDER_TYPE=oidc \
SSO_PROVIDER_ID=acme-okta \
SSO_ISSUER=https://dev-1234567.okta.com \
SSO_DOMAIN=acme.com \
SSO_USER_EMAIL=admin@acme.com \
SSO_ORGANIZATION_ID=org_123 \
SSO_OIDC_CLIENT_ID=your-client-id \
SSO_OIDC_CLIENT_SECRET=your-client-secret \
bun run packages/db/scripts/register-sso-provider.ts

SAML example:

DATABASE_URL=... \
SSO_ENABLED=true \
NEXT_PUBLIC_APP_URL=https://sim.example.com \
SSO_PROVIDER_TYPE=saml \
SSO_PROVIDER_ID=acme-adfs \
SSO_ISSUER=https://adfs.acme.com/adfs/services/trust \
SSO_SAML_AUDIENCE=https://sim.example.com \
SSO_DOMAIN=acme.com \
SSO_USER_EMAIL=admin@acme.com \
SSO_ORGANIZATION_ID=org_123 \
SSO_SAML_ENTRY_POINT=https://adfs.acme.com/adfs/ls \
SSO_SAML_CERT="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
bun run packages/db/scripts/register-sso-provider.ts

The script prints the callback URL to register in the identity provider. These commands configure the database; persist the SSO feature flags in the running application's environment separately.

To remove one provider:

DATABASE_URL=... \
SSO_USER_EMAIL=admin@acme.com \
SSO_PROVIDER_ID=acme-okta \
bun run packages/db/scripts/deregister-sso-provider.ts

Omitting SSO_PROVIDER_ID removes all providers owned by that account.

Related docs

• Verified domains
• Directory provisioning
• Okta provisioning
• Microsoft Entra provisioning
• Session policies