Skip to content

sso.mdx

Latest commit

 

History

History
345 lines (259 loc) · 12.9 KB

sso.mdx

File metadata and controls

345 lines (259 loc) · 12.9 KB
title Single Sign-On (SSO)
description Configure SAML 2.0 or OIDC-based single sign-on for your organization

import { Callout } from 'fumadocs-ui/components/callout' import { Tab, Tabs } from 'fumadocs-ui/components/tabs' import { FAQ } from '@/components/ui/faq'

Single Sign-On lets your team sign in to Sim through your company's identity provider instead of managing separate passwords. Sim supports both OIDC and SAML 2.0.

Requirements

Sim Cloud: Enterprise plan. You must be a workspace owner or admin.

Self-hosted: Set SSO_ENABLED=true and NEXT_PUBLIC_SSO_ENABLED=true in your environment. No plan requirement.

Setup

1. Open SSO settings

Go to Settings → Enterprise → Single Sign-On in your workspace.

2. Choose a protocol

Protocol Use when
OIDC Your IdP supports OpenID Connect — Okta, Microsoft Entra ID, Auth0, Google Workspace
SAML 2.0 Your IdP is SAML-only — ADFS, Shibboleth, or older enterprise IdPs

3. Fill in the form

Fields required for both protocols:

Field What to enter
Provider ID A short slug identifying this connection, e.g. okta or azure-ad. Letters, numbers, and dashes only.
Issuer URL The identity provider's issuer URL. Must be HTTPS.
Domain Your organization's email domain, e.g. company.com. Users with this domain will be routed through SSO at sign-in.

OIDC additional fields:

Field What to enter
Client ID The application client ID from your IdP.
Client Secret The client secret from your IdP.
Scopes Comma-separated OIDC scopes. Default: openid,profile,email.
For OIDC, Sim automatically fetches endpoints (`authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, `jwks_uri`) from your issuer's `/.well-known/openid-configuration` discovery document. You only need to provide the issuer URL.

SAML additional fields:

Field What to enter
Entry Point URL The IdP's SSO service URL where Sim sends authentication requests.
Identity Provider Certificate The Base-64 encoded X.509 certificate from your IdP for verifying assertions.

4. Copy the Callback URL

The Callback URL shown in the form is the endpoint your identity provider must redirect users back to after authentication. Copy it and register it in your IdP before saving.

OIDC providers (Okta, Microsoft Entra ID, Google Workspace, Auth0):

https://simstudio.ai/api/auth/sso/callback/{provider-id}

SAML providers (ADFS, Shibboleth):

https://simstudio.ai/api/auth/sso/saml2/callback/{provider-id}

For self-hosted, replace simstudio.ai with your instance hostname.

5. Save and test

Click Save. To test, sign out and use the Sign in with SSO button on the login page. Enter an email address at your configured domain — Sim will redirect you to your identity provider.

Provider Guides

<Tabs items={['Okta', 'Microsoft Entra ID', 'Google Workspace', 'ADFS']}>

Okta (OIDC)

In Okta (official docs):

  1. Go to Applications → Create App Integration
  2. Select OIDC - OpenID Connect, then Web Application
  3. Set the Sign-in redirect URI to your Sim callback URL: 
    https://simstudio.ai/api/auth/sso/callback/okta
  4. Under Assignments, grant access to the relevant users or groups
  5. Copy the Client ID and Client Secret from the app's General tab
  6. Your Okta domain is the hostname of your admin console, e.g. dev-1234567.okta.com

In Sim:

Field Value
Provider Type OIDC
Provider ID okta
Issuer URL https://dev-1234567.okta.com/oauth2/default
Domain company.com
Client ID From Okta app
Client Secret From Okta app
The issuer URL uses Okta's default authorization server (`/oauth2/default`), which is pre-configured on every Okta org. If you created a custom authorization server, replace `default` with your server name.

Microsoft Entra ID (OIDC)

In Azure (official docs):

  1. Go to Microsoft Entra ID → App registrations → New registration
  2. Under Redirect URI, select Web and enter your Sim callback URL: 
    https://simstudio.ai/api/auth/sso/callback/azure-ad
  3. After registration, go to Certificates & secrets → New client secret and copy the value immediately — it won't be shown again
  4. Go to Overview and copy the Application (client) ID and Directory (tenant) ID

In Sim:

Field Value
Provider Type OIDC
Provider ID azure-ad
Issuer URL https://login.microsoftonline.com/{tenant-id}/v2.0
Domain company.com
Client ID Application (client) ID
Client Secret Secret value
Replace `{tenant-id}` with your Directory (tenant) ID from the app's Overview page. Sim auto-discovers token and JWKS endpoints from the issuer.

Google Workspace (OIDC)

In Google Cloud Console (official docs):

  1. Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
  2. Set the application type to Web application
  3. Add your Sim callback URL to Authorized redirect URIs: 
    https://simstudio.ai/api/auth/sso/callback/google-workspace
  4. Copy the Client ID and Client Secret

In Sim:

Field Value
Provider Type OIDC
Provider ID google-workspace
Issuer URL https://accounts.google.com
Domain company.com
Client ID From Google Cloud Console
Client Secret From Google Cloud Console
To restrict sign-in to your Google Workspace domain, configure the OAuth consent screen and ensure your app is set to **Internal** (Workspace users only) under **User type**. Setting the app to Internal limits access to users within your Google Workspace organization.

ADFS (SAML 2.0)

In ADFS (official docs):

  1. Open AD FS Management → Relying Party Trusts → Add Relying Party Trust
  2. Choose Claims aware, then Enter data about the relying party manually
  3. Set the Relying party identifier (Entity ID) to your Sim base URL: 
    https://simstudio.ai
    For self-hosted, use your instance's base URL (e.g. https://sim.company.com)
  4. Add an endpoint: SAML Assertion Consumer Service (HTTP POST) with the URL: 
    https://simstudio.ai/api/auth/sso/saml2/callback/adfs
    For self-hosted: https://sim.company.com/api/auth/sso/saml2/callback/adfs
  5. Export the Token-signing certificate from Certificates: right-click → View Certificate → Details → Copy to File, choose Base-64 encoded X.509 (.CER). The .cer file is PEM-encoded — rename it to .pem before pasting its contents into Sim.
  6. Note the ADFS Federation Service endpoint URL (e.g. https://adfs.company.com/adfs/ls)

In Sim:

Field Value
Provider Type SAML
Provider ID adfs
Issuer URL https://simstudio.ai
Domain company.com
Entry Point URL https://adfs.company.com/adfs/ls
Certificate Contents of the .pem file
For ADFS, the **Issuer URL** field is the SP entity ID — the identifier ADFS uses to identify Sim as a relying party. It must match the **Relying party identifier** you registered in ADFS.

How sign-in works after setup

Once SSO is configured, users with your domain (company.com) can sign in through your identity provider:

  1. User goes to simstudio.ai and clicks Sign in with SSO
  2. They enter their work email (e.g. alice@company.com)
  3. Sim redirects them to your identity provider
  4. After authenticating, they are returned to Sim and added to your organization automatically
  5. They land in the workspace

Users who sign in via SSO for the first time are automatically provisioned and added to your organization — no manual invite required.

Password-based login remains available. Forcing all organization members to use SSO exclusively is not yet supported. **Self-hosted:** Automatic organization provisioning requires `ORGANIZATIONS_ENABLED=true` in addition to `SSO_ENABLED=true`. Without it, SSO authentication still works — users get a valid session — but they are not automatically added to an organization.

<FAQ items={[ { question: "Which SSO providers are supported?", answer: "Any identity provider that supports OIDC or SAML 2.0. This includes Okta, Microsoft Entra ID (Azure AD), Google Workspace, Auth0, OneLogin, JumpCloud, Ping Identity, ADFS, Shibboleth, and more." }, { question: "What is the Domain field used for?", answer: "The domain (e.g. company.com) is how Sim routes users to the right identity provider. When a user enters their email on the SSO sign-in page, Sim matches their email domain to a registered SSO provider and redirects them there." }, { question: "Do I need to provide OIDC endpoints manually?", answer: "No. For OIDC providers, Sim automatically fetches the authorization, token, and JWKS endpoints from the discovery document at {issuer}/.well-known/openid-configuration. You only need to provide the issuer URL." }, { question: "What happens when a user signs in with SSO for the first time?", answer: "Sim creates an account for them automatically and adds them to your organization. No manual invite is needed. They are assigned the member role by default." }, { question: "Can I still use email/password login after enabling SSO?", answer: "Yes. Enabling SSO does not disable password-based login. Users can still sign in with their email and password if they have one. Forced SSO (requiring all users on the domain to use SSO) is not yet supported." }, { question: "Who can configure SSO on Sim Cloud?", answer: "Organization owners and admins can configure SSO. You must be on the Enterprise plan." }, { question: "What is the Callback URL?", answer: "The Callback URL (also called Redirect URI or ACS URL) is the endpoint in Sim that receives the authentication response from your identity provider. For OIDC providers it follows the format: https://simstudio.ai/api/auth/sso/callback/{provider-id}. For SAML providers it is: https://simstudio.ai/api/auth/sso/saml2/callback/{provider-id}. You must register this URL in your identity provider before SSO will work." }, { question: "How do I update or replace an existing SSO configuration?", answer: "Open Settings → Enterprise → Single Sign-On and click Edit. Update the fields and save. The existing provider configuration is replaced." } ]} />

Self-hosted setup

Self-hosted deployments use environment variables instead of the billing/plan check.

Environment variables

# Required
SSO_ENABLED=true
NEXT_PUBLIC_SSO_ENABLED=true

# Required if you want users auto-added to your organization on first SSO sign-in
ORGANIZATIONS_ENABLED=true
NEXT_PUBLIC_ORGANIZATIONS_ENABLED=true

You can register providers through the Settings UI (same as cloud) or by running the registration script directly against your database.

Script-based registration

Use this when you need to register an SSO provider without going through the UI — for example, during initial deployment or CI/CD automation.

# OIDC example (Okta)
SSO_ENABLED=true \
NEXT_PUBLIC_APP_URL=https://your-instance.com \
SSO_PROVIDER_TYPE=oidc \
SSO_PROVIDER_ID=okta \
SSO_ISSUER=https://dev-1234567.okta.com/oauth2/default \
SSO_DOMAIN=company.com \
SSO_USER_EMAIL=admin@company.com \
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 (ADFS)
SSO_ENABLED=true \
NEXT_PUBLIC_APP_URL=https://your-instance.com \
SSO_PROVIDER_TYPE=saml \
SSO_PROVIDER_ID=adfs \
SSO_ISSUER=https://your-instance.com \
SSO_DOMAIN=company.com \
SSO_USER_EMAIL=admin@company.com \
SSO_SAML_ENTRY_POINT=https://adfs.company.com/adfs/ls \
SSO_SAML_CERT="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
bun run packages/db/scripts/register-sso-provider.ts

The script outputs the callback URL to configure in your IdP once it completes.

To remove a provider:

SSO_USER_EMAIL=admin@company.com \
bun run packages/db/scripts/deregister-sso-provider.ts