Skip to content

Commit 0cd14f4

Browse files
waleedlatif1waleedlatif1
authored
improvement(sso): fix provider lookup, migrate UI to emcn, add enterprise SSO docs (#4238)
* improvement(sso): fix provider lookup, migrate UI to emcn, add enterprise SSO docs * fix(sso): add org membership guard on providers route, fix idpMetadata round-trip * fix(sso): add org membership guard on register route, fix SP entityID, remove fullError leak * fix(sso): fix SAML script callbackUrl and SP entityID to use app base URL * fix(sso): correct SAML callback URL path in script header comment * fix(sso): restrict SSO provider read/write to org owners and admins * docs(sso): restructure page, fix provider guide accuracy, add external doc links * fix(sso): correct SAML callback path and generate idpMetadata from cert+entryPoint * fix(sso): always require NEXT_PUBLIC_APP_URL for SAML SP metadata entityID * fix(sso): scope provider query to org only when organizationId is provided * fix(sso): escape XML special chars in script idpMetadata generation * fix(sso): final audit corrections — saml mapping, xml escaping, self-hosted org guard * fix(sso): redact oidc client secret in providers response, add self-hosted org admin guard * fix(sso): scope redacted-secret lookup to caller's org or userId * fix(sso): null out oidcConfig on parse failure to prevent unredacted secret leak * fix(sso): use issuer as entityID in auto-generated idp metadata xml
1 parent d9209f9 commit 0cd14f4

File tree

11 files changed

+846
-371
lines changed

11 files changed

+846
-371
lines changed

‎apps/docs/content/docs/en/enterprise/index.mdx‎

Lines changed: 2 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -34,26 +34,9 @@ Define permission groups to control what features and integrations team members
3434

3535
## Single Sign-On (SSO)
3636

37-
Enterprise authentication with SAML 2.0 and OIDC support for centralized identity management.
37+
Enterprise authentication with SAML 2.0 and OIDC support. Works with Okta, Azure AD (Entra ID), Google Workspace, ADFS, and any standard OIDC or SAML 2.0 provider.
3838

39-
### Supported Providers
40-
41-
- Okta
42-
- Azure AD / Entra ID
43-
- Google Workspace
44-
- OneLogin
45-
- Any SAML 2.0 or OIDC provider
46-
47-
### Setup
48-
49-
1. Navigate to **Settings** → **SSO** in your workspace
50-
2. Choose your identity provider
51-
3. Configure the connection using your IdP's metadata
52-
4. Enable SSO for your organization
53-
54-
<Callout type="info">
55-
Once SSO is enabled, team members authenticate through your identity provider instead of email/password.
56-
</Callout>
39+
See the [SSO setup guide](/docs/enterprise/sso) for step-by-step instructions and provider-specific configuration.
5740

5841
---
5942

‎apps/docs/content/docs/en/enterprise/meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"title": "Enterprise",
3+
"pages": ["index", "sso"],
4+
"defaultOpen": false
5+
}

‎apps/docs/content/docs/en/enterprise/sso.mdx‎

Lines changed: 345 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,345 @@
1+
---
2+
title: Single Sign-On (SSO)
3+
description: Configure SAML 2.0 or OIDC-based single sign-on for your organization
4+
---
5+
6+
import { Callout } from 'fumadocs-ui/components/callout'
7+
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
8+
import { FAQ } from '@/components/ui/faq'
9+
10+
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.
11+
12+
---
13+
14+
## Requirements
15+
16+
**Sim Cloud:** Enterprise plan. You must be a workspace owner or admin.
17+
18+
**Self-hosted:** Set `SSO_ENABLED=true` and `NEXT_PUBLIC_SSO_ENABLED=true` in your environment. No plan requirement.
19+
20+
---
21+
22+
## Setup
23+
24+
### 1. Open SSO settings
25+
26+
Go to **Settings → Enterprise → Single Sign-On** in your workspace.
27+
28+
### 2. Choose a protocol
29+
30+
| Protocol | Use when |
31+
|----------|----------|
32+
| **OIDC** | Your IdP supports OpenID Connect — Okta, Microsoft Entra ID, Auth0, Google Workspace |
33+
| **SAML 2.0** | Your IdP is SAML-only — ADFS, Shibboleth, or older enterprise IdPs |
34+
35+
### 3. Fill in the form
36+
37+
**Fields required for both protocols:**
38+
39+
| Field | What to enter |
40+
|-------|--------------|
41+
| **Provider ID** | A short slug identifying this connection, e.g. `okta` or `azure-ad`. Letters, numbers, and dashes only. |
42+
| **Issuer URL** | The identity provider's issuer URL. Must be HTTPS. |
43+
| **Domain** | Your organization's email domain, e.g. `company.com`. Users with this domain will be routed through SSO at sign-in. |
44+
45+
**OIDC additional fields:**
46+
47+
| Field | What to enter |
48+
|-------|--------------|
49+
| **Client ID** | The application client ID from your IdP. |
50+
| **Client Secret** | The client secret from your IdP. |
51+
| **Scopes** | Comma-separated OIDC scopes. Default: `openid,profile,email`. |
52+
53+
<Callout type="info">
54+
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.
55+
</Callout>
56+
57+
**SAML additional fields:**
58+
59+
| Field | What to enter |
60+
|-------|--------------|
61+
| **Entry Point URL** | The IdP's SSO service URL where Sim sends authentication requests. |
62+
| **Identity Provider Certificate** | The Base-64 encoded X.509 certificate from your IdP for verifying assertions. |
63+
64+
### 4. Copy the Callback URL
65+
66+
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.
67+
68+
**OIDC providers** (Okta, Microsoft Entra ID, Google Workspace, Auth0):
69+
```
70+
https://simstudio.ai/api/auth/sso/callback/{provider-id}
71+
```
72+
73+
**SAML providers** (ADFS, Shibboleth):
74+
```
75+
https://simstudio.ai/api/auth/sso/saml2/callback/{provider-id}
76+
```
77+
78+
For self-hosted, replace `simstudio.ai` with your instance hostname.
79+
80+
### 5. Save and test
81+
82+
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.
83+
84+
---
85+
86+
## Provider Guides
87+
88+
<Tabs items={['Okta', 'Microsoft Entra ID', 'Google Workspace', 'ADFS']}>
89+
90+
<Tab value="Okta">
91+
92+
### Okta (OIDC)
93+
94+
**In Okta** ([official docs](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)):
95+
96+
1. Go to **Applications → Create App Integration**
97+
2. Select **OIDC - OpenID Connect**, then **Web Application**
98+
3. Set the **Sign-in redirect URI** to your Sim callback URL:
99+
```
100+
https://simstudio.ai/api/auth/sso/callback/okta
101+
```
102+
4. Under **Assignments**, grant access to the relevant users or groups
103+
5. Copy the **Client ID** and **Client Secret** from the app's **General** tab
104+
6. Your Okta domain is the hostname of your admin console, e.g. `dev-1234567.okta.com`
105+
106+
**In Sim:**
107+
108+
| Field | Value |
109+
|-------|-------|
110+
| Provider Type | OIDC |
111+
| Provider ID | `okta` |
112+
| Issuer URL | `https://dev-1234567.okta.com/oauth2/default` |
113+
| Domain | `company.com` |
114+
| Client ID | From Okta app |
115+
| Client Secret | From Okta app |
116+
117+
<Callout type="info">
118+
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.
119+
</Callout>
120+
121+
</Tab>
122+
123+
<Tab value="Microsoft Entra ID">
124+
125+
### Microsoft Entra ID (OIDC)
126+
127+
**In Azure** ([official docs](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)):
128+
129+
1. Go to **Microsoft Entra ID → App registrations → New registration**
130+
2. Under **Redirect URI**, select **Web** and enter your Sim callback URL:
131+
```
132+
https://simstudio.ai/api/auth/sso/callback/azure-ad
133+
```
134+
3. After registration, go to **Certificates & secrets → New client secret** and copy the value immediately — it won't be shown again
135+
4. Go to **Overview** and copy the **Application (client) ID** and **Directory (tenant) ID**
136+
137+
**In Sim:**
138+
139+
| Field | Value |
140+
|-------|-------|
141+
| Provider Type | OIDC |
142+
| Provider ID | `azure-ad` |
143+
| Issuer URL | `https://login.microsoftonline.com/{tenant-id}/v2.0` |
144+
| Domain | `company.com` |
145+
| Client ID | Application (client) ID |
146+
| Client Secret | Secret value |
147+
148+
<Callout type="info">
149+
Replace `{tenant-id}` with your Directory (tenant) ID from the app's Overview page. Sim auto-discovers token and JWKS endpoints from the issuer.
150+
</Callout>
151+
152+
</Tab>
153+
154+
<Tab value="Google Workspace">
155+
156+
### Google Workspace (OIDC)
157+
158+
**In Google Cloud Console** ([official docs](https://developers.google.com/identity/openid-connect/openid-connect)):
159+
160+
1. Go to **APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID**
161+
2. Set the application type to **Web application**
162+
3. Add your Sim callback URL to **Authorized redirect URIs**:
163+
```
164+
https://simstudio.ai/api/auth/sso/callback/google-workspace
165+
```
166+
4. Copy the **Client ID** and **Client Secret**
167+
168+
**In Sim:**
169+
170+
| Field | Value |
171+
|-------|-------|
172+
| Provider Type | OIDC |
173+
| Provider ID | `google-workspace` |
174+
| Issuer URL | `https://accounts.google.com` |
175+
| Domain | `company.com` |
176+
| Client ID | From Google Cloud Console |
177+
| Client Secret | From Google Cloud Console |
178+
179+
<Callout type="info">
180+
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.
181+
</Callout>
182+
183+
</Tab>
184+
185+
<Tab value="ADFS">
186+
187+
### ADFS (SAML 2.0)
188+
189+
**In ADFS** ([official docs](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust)):
190+
191+
1. Open **AD FS Management → Relying Party Trusts → Add Relying Party Trust**
192+
2. Choose **Claims aware**, then **Enter data about the relying party manually**
193+
3. Set the **Relying party identifier** (Entity ID) to your Sim base URL:
194+
```
195+
https://simstudio.ai
196+
```
197+
For self-hosted, use your instance's base URL (e.g. `https://sim.company.com`)
198+
4. Add an endpoint: **SAML Assertion Consumer Service** (HTTP POST) with the URL:
199+
```
200+
https://simstudio.ai/api/auth/sso/saml2/callback/adfs
201+
```
202+
For self-hosted: `https://sim.company.com/api/auth/sso/saml2/callback/adfs`
203+
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.
204+
6. Note the **ADFS Federation Service endpoint URL** (e.g. `https://adfs.company.com/adfs/ls`)
205+
206+
**In Sim:**
207+
208+
| Field | Value |
209+
|-------|-------|
210+
| Provider Type | SAML |
211+
| Provider ID | `adfs` |
212+
| Issuer URL | `https://simstudio.ai` |
213+
| Domain | `company.com` |
214+
| Entry Point URL | `https://adfs.company.com/adfs/ls` |
215+
| Certificate | Contents of the `.pem` file |
216+
217+
<Callout type="info">
218+
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.
219+
</Callout>
220+
221+
</Tab>
222+
223+
</Tabs>
224+
225+
---
226+
227+
## How sign-in works after setup
228+
229+
Once SSO is configured, users with your domain (`company.com`) can sign in through your identity provider:
230+
231+
1. User goes to `simstudio.ai` and clicks **Sign in with SSO**
232+
2. They enter their work email (e.g. `alice@company.com`)
233+
3. Sim redirects them to your identity provider
234+
4. After authenticating, they are returned to Sim and added to your organization automatically
235+
5. They land in the workspace
236+
237+
Users who sign in via SSO for the first time are automatically provisioned and added to your organization — no manual invite required.
238+
239+
<Callout type="info">
240+
Password-based login remains available. Forcing all organization members to use SSO exclusively is not yet supported.
241+
</Callout>
242+
243+
<Callout type="info">
244+
**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.
245+
</Callout>
246+
247+
---
248+
249+
<FAQ items={[
250+
{
251+
question: "Which SSO providers are supported?",
252+
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."
253+
},
254+
{
255+
question: "What is the Domain field used for?",
256+
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."
257+
},
258+
{
259+
question: "Do I need to provide OIDC endpoints manually?",
260+
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."
261+
},
262+
{
263+
question: "What happens when a user signs in with SSO for the first time?",
264+
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."
265+
},
266+
{
267+
question: "Can I still use email/password login after enabling SSO?",
268+
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."
269+
},
270+
{
271+
question: "Who can configure SSO on Sim Cloud?",
272+
answer: "Organization owners and admins can configure SSO. You must be on the Enterprise plan."
273+
},
274+
{
275+
question: "What is the Callback URL?",
276+
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."
277+
},
278+
{
279+
question: "How do I update or replace an existing SSO configuration?",
280+
answer: "Open Settings → Enterprise → Single Sign-On and click Edit. Update the fields and save. The existing provider configuration is replaced."
281+
}
282+
]} />
283+
284+
---
285+
286+
## Self-hosted setup
287+
288+
Self-hosted deployments use environment variables instead of the billing/plan check.
289+
290+
### Environment variables
291+
292+
```bash
293+
# Required
294+
SSO_ENABLED=true
295+
NEXT_PUBLIC_SSO_ENABLED=true
296+
297+
# Required if you want users auto-added to your organization on first SSO sign-in
298+
ORGANIZATIONS_ENABLED=true
299+
NEXT_PUBLIC_ORGANIZATIONS_ENABLED=true
300+
```
301+
302+
You can register providers through the **Settings UI** (same as cloud) or by running the registration script directly against your database.
303+
304+
### Script-based registration
305+
306+
Use this when you need to register an SSO provider without going through the UI — for example, during initial deployment or CI/CD automation.
307+
308+
```bash
309+
# OIDC example (Okta)
310+
SSO_ENABLED=true \
311+
NEXT_PUBLIC_APP_URL=https://your-instance.com \
312+
SSO_PROVIDER_TYPE=oidc \
313+
SSO_PROVIDER_ID=okta \
314+
SSO_ISSUER=https://dev-1234567.okta.com/oauth2/default \
315+
SSO_DOMAIN=company.com \
316+
SSO_USER_EMAIL=admin@company.com \
317+
SSO_OIDC_CLIENT_ID=your-client-id \
318+
SSO_OIDC_CLIENT_SECRET=your-client-secret \
319+
bun run packages/db/scripts/register-sso-provider.ts
320+
```
321+
322+
```bash
323+
# SAML example (ADFS)
324+
SSO_ENABLED=true \
325+
NEXT_PUBLIC_APP_URL=https://your-instance.com \
326+
SSO_PROVIDER_TYPE=saml \
327+
SSO_PROVIDER_ID=adfs \
328+
SSO_ISSUER=https://your-instance.com \
329+
SSO_DOMAIN=company.com \
330+
SSO_USER_EMAIL=admin@company.com \
331+
SSO_SAML_ENTRY_POINT=https://adfs.company.com/adfs/ls \
332+
SSO_SAML_CERT="-----BEGIN CERTIFICATE-----
333+
...
334+
-----END CERTIFICATE-----" \
335+
bun run packages/db/scripts/register-sso-provider.ts
336+
```
337+
338+
The script outputs the callback URL to configure in your IdP once it completes.
339+
340+
To remove a provider:
341+
342+
```bash
343+
SSO_USER_EMAIL=admin@company.com \
344+
bun run packages/db/scripts/deregister-sso-provider.ts
345+
```

‎apps/docs/content/docs/en/meta.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
"execution",
2626
"permissions",
2727
"self-hosting",
28-
"./enterprise/index",
28+
"enterprise",
2929
"./keyboard-shortcuts/index"
3030
],
3131
"defaultOpen": false

‎apps/docs/public/static/enterprise/sso-form.png‎

208 KB
Loading

0 commit comments

Comments
 (0)