Skip to content
Try for free
On this page

Enterprise

Single sign-on (SSO)

Configure SAML or OpenID Connect sign-in for your organization

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:

TabConfigure
Sign-inIdentity providers, callback URLs, first-sign-in membership, and allowed sign-in methods
DomainsDomain ownership shared by SSO and SCIM
ProvisioningSCIM connection, tokens, rules, group mappings, and activity

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

FieldValue
Provider IDLetters, numbers, and dashes only. Choose a globally unique ID, such as acme-okta. Sim rejects an ID already used by another organization.
Issuer URLYour identity provider's HTTPS issuer URL
DomainThe verified email domain served by this connection, such as acme.com
On first SSO sign-inAutomatic adds new organization members; Invite only authenticates without adding membership. See membership behavior.

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:

ProtocolCallback format
OIDChttps://<your-sim-domain>/api/auth/sso/callback/{provider-id}
SAMLhttps://<your-sim-domain>/api/auth/sso/saml2/callback/{provider-id}

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

  1. In the Okta Admin Console, open Applications and Resources → Applications → Create App Integration. These steps use Classic experience; select OIDC - OpenID Connect, then Web Application.
  2. Set Sign-in redirect URI to your chosen Sim callback:
    text
    https://<your-sim-domain>/api/auth/sso/callback/acme-okta
  3. Under Assignments, grant access to the people or groups who should sign in.
  4. Copy Client ID and Client Secret from General.
  5. Copy your Okta organization domain from the Admin Console account menu, for example dev-1234567.okta.com. Do not use its -admin hostname.
Sim fieldValue
Provider typeOIDC
Provider IDacme-okta
Issuer URLhttps://dev-1234567.okta.com
Domainacme.com
Client IDFrom the Okta app
Client secretFrom the Okta app

Use the organization issuer for ordinary sign-in. A custom authorization server requires API Access Management and uses https://<your-okta-domain>/oauth2/<authorization-server-id>. The default custom server is included in the Integrator Free Plan but not every production organization. See Okta authorization servers and Find your Okta domain.

To launch Sim from an Okta dashboard tile, set Login initiated by to Either Okta or App, show the icon, and choose the flow that redirects to the app to initiate OIDC login. Set Initiate login URI to the saved provider's Initiate login URL from Sim:

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

See Okta OIDC setup. For SCIM, the creation experience matters: Classic OIDC apps need a separate provisioning integration, while the newer Okta Integration Wizard can support SCIM on OIDC. See Okta provisioning.

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:

ModeOrganization membership
AutomaticAdds a new account as a Member without an organization invitation. Team seat counts grow with membership; fixed-seat plans require available capacity. IdP role claims do not select the organization role.
Invite onlyAuthenticates the account without creating membership. Existing membership and workspace access remain available; grant new access separately.

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:

Code
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:

Code
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:

Code
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:

Code
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

Was this helpful?
Suggest an edit