Skip to content

docs(sso): correct callback host and issuer guidance, document Entra SAML and IdP-initiated behavior#6334

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
waleedlatif1 merged 3 commits into from
Aug 6, 2026
Merged

docs(sso): correct callback host and issuer guidance, document Entra SAML and IdP-initiated behavior #6334

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
968ceb4
docs(sso): use the deployed host in callback and entity ID examples
waleedlatif1 Aug 6, 2026
bf5d39d
docs(sso): correct host, issuer, and provider-id guidance; document E…
waleedlatif1 Aug 6, 2026
fde9e82
docs(sso): send Entra federation metadata to the field that reads it
waleedlatif1 Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 57 additions & 14 deletions apps/docs/content/docs/en/platform/enterprise/sso.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -16,9 +16,11 @@ Single Sign-On lets your team sign in to Sim through your company's identity pro

<Callout type="warning">
[Verify your email domain](/platform/enterprise/verified-domains) first. SSO cannot be saved until the domain shows as **Verified**, and DNS changes take time to propagate.

The verified domain is what authorizes your identity provider. Removing it later immediately disables SSO sign-in for everyone on that domain until it is verified again.
</Callout>

Decide your **Provider ID** before configuring your identity provider — it becomes part of the callback URL you register there, so changing it later means redoing that step.
Decide your **Provider ID** before configuring your identity provider. It becomes part of the callback URL you register there, and it is **fixed once saved** — changing it later means deleting the provider and setting it up again.

---

Expand DownExpand Up@@ -72,12 +74,12 @@ The **Callback URL** shown in the form is the endpoint your identity provider mu

**OIDC providers** (Okta, Microsoft Entra ID, Google Workspace, Auth0):
```
https://sim.ai/api/auth/sso/callback/{provider-id}
https://www.sim.ai/api/auth/sso/callback/{provider-id}
```

**SAML providers** (ADFS, Shibboleth):
```
https://sim.ai/api/auth/sso/saml2/callback/{provider-id}
https://www.sim.ai/api/auth/sso/saml2/callback/{provider-id}
```

### 5. Save and test
Expand All@@ -88,7 +90,7 @@ Click **Save**. To test, sign out and use the **Sign in with SSO** button on the

## Provider Guides

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

<Tab value="Okta">

Expand All@@ -100,7 +102,7 @@ Click **Save**. To test, sign out and use the **Sign in with SSO** button on the
2. Select **OIDC - OpenID Connect**, then **Web Application**
3. Set the **Sign-in redirect URI** to your Sim callback URL:
```
https://sim.ai/api/auth/sso/callback/okta
https://www.sim.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
Expand DownExpand Up@@ -130,7 +132,7 @@ The issuer URL uses Okta's default authorization server, which is pre-configured
1. Go to **Microsoft Entra ID → App registrations → New registration**
2. Under **Redirect URI**, select **Web** and enter your Sim callback URL, using the Provider ID you chose:
```
https://sim.ai/api/auth/sso/callback/azure-ad-acme
https://www.sim.ai/api/auth/sso/callback/azure-ad-acme
```
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**
Expand All@@ -150,6 +152,41 @@ The issuer URL uses Okta's default authorization server, which is pre-configured

</Tab>

<Tab value="Microsoft Entra ID (SAML)">

### Microsoft Entra ID (SAML 2.0)

Use this when your tenant is configured for SAML rather than OIDC. Both are supported; OIDC is simpler if you have the choice.

**In Azure** ([official docs](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso)):

1. Go to **Enterprise applications → New application → Create your own application**, choose **Integrate any other application you don't find in the gallery**
2. Open **Single sign-on** and select **SAML**
3. Edit **Basic SAML Configuration** and set both values from Sim's SSO settings page:
- **Identifier (Entity ID)** — the **SP Entity ID** field
- **Reply URL (Assertion Consumer Service URL)** — the **ACS URL** field
4. Under **Attributes & Claims**, confirm the default claims are present. Sim reads the standard schema claim URIs for email, name, and name identifier
5. Under **SAML Certificates**, download **Certificate (Base64)**. Its contents go in Sim's **Certificate** field, which is required. You can optionally also download **Federation Metadata XML** and paste it into Sim's **IDP Metadata XML** field under **Advanced Options** — it does not replace the certificate
6. From the **Set up** panel for your application, copy the **Login URL** and the **Microsoft Entra Identifier**
7. Under **Users and groups**, assign the people who should be able to sign in — Microsoft rejects unassigned users before they reach Sim

**In Sim:**

| Field | Value |
|-------|-------|
| Provider Type | SAML |
| Provider ID | `azure-ad-acme` (must be globally unique) |
| Issuer URL | **Microsoft Entra Identifier**, e.g. `https://sts.windows.net/{tenant-id}/` |
| Domain | `company.com` |
| Entry Point URL | **Login URL** from Entra |
| Certificate | Contents of the Base64 certificate |

<Callout type="info">
The **Identifier (Entity ID)** you set in Entra is what Sim validates the assertion's audience against. If it does not match the **SP Entity ID** shown in Sim exactly, sign-in fails with an audience mismatch.
</Callout>

</Tab>

<Tab value="Google Workspace">

### Google Workspace (OIDC)
Expand All@@ -160,7 +197,7 @@ The issuer URL uses Okta's default authorization server, which is pre-configured
2. Set the application type to **Web application**
3. Add your Sim callback URL to **Authorized redirect URIs**:
```
https://sim.ai/api/auth/sso/callback/google-workspace
https://www.sim.ai/api/auth/sso/callback/google-workspace
```
4. Copy the **Client ID** and **Client Secret**

Expand DownExpand Up@@ -189,13 +226,13 @@ The issuer URL uses Okta's default authorization server, which is pre-configured

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:
3. Set the **Relying party identifier** (Entity ID) to the **SP Entity ID** shown in Sim's SSO settings. SAML compares the assertion's audience against it, so it must match exactly:
```
https://sim.ai
https://www.sim.ai
```
4. Add an endpoint: **SAML Assertion Consumer Service** (HTTP POST) with the URL:
```
https://sim.ai/api/auth/sso/saml2/callback/adfs
https://www.sim.ai/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`)
Expand All@@ -206,13 +243,15 @@ The issuer URL uses Okta's default authorization server, which is pre-configured
|-------|-------|
| Provider Type | SAML |
| Provider ID | `adfs` |
| Issuer URL | `https://sim.ai` |
| Issuer URL | `https://adfs.company.com/adfs/services/trust` (the ADFS Federation Service identifier) |
| Domain | `company.com` |
| Entry Point URL | `https://adfs.company.com/adfs/ls` |
| Certificate | Contents of the `.pem` file |

<Callout type="info">
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.
The **Issuer URL** is the identity provider's own identifier, found in ADFS under **Service → Federation Service Properties → Federation Service identifier**. It is not Sim's URL — Sim's identifier is the **SP Entity ID** shown in the SSO settings, which you register in ADFS as the relying party identifier.

Sim requires this field to use `https`. ADFS often defaults its Federation Service identifier to an `http://` URI; if yours does, change it to `https` in ADFS so both sides agree.
</Callout>

</Tab>
Expand All@@ -233,6 +272,10 @@ Once SSO is configured, users with your domain (`company.com`) can sign in throu

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

<Callout type="warning">
Sign-in must start from Sim. Launching from your identity provider's app portal (Microsoft's **My Apps**, Okta's dashboard tile) sends an unsolicited assertion, which Sim rejects. This is deliberate — accepting them would let anyone replay an assertion into your tenant — but it means an IdP-initiated test fails even when the configuration is correct.
</Callout>

SSO provisioning creates internal organization members. External workspace members are different: they are invited to a specific workspace without joining your organization or consuming one of your seats.

<Callout type="info">
Expand DownExpand Up@@ -264,15 +307,15 @@ SSO provisioning creates internal organization members. External workspace membe
},
{
question: "A user already has an account with the same email — what happens when they sign in with SSO?",
answer: "Sim links the SSO identity to that account automatically. Linking is authorized by your verified domain: because you proved ownership of the domain before configuring SSO, Sim treats your identity provider as authoritative for email addresses on it. This works the same for OIDC and SAML, and does not depend on your IdP sending an email_verified claim — Microsoft Entra, for example, never sends one."
answer: "Sim links the SSO identity to that account automatically. Linking is authorized by your verified domain: because you proved ownership of the domain before configuring SSO, Sim treats your identity provider as authoritative for email addresses on it. This works the same for OIDC and SAML, and does not depend on your IdP sending an email_verified claim — Microsoft Entra, for example, never sends one. Matching is by email address, so the address your IdP asserts must be identical to the one on the existing account. If it differs — a privileged or admin variant such as p-alice@company.com, or a different alias — Sim treats it as a new person and creates a separate account rather than linking."
},
{
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://sim.ai/api/auth/sso/callback/{provider-id}. For SAML providers it is: https://sim.ai/api/auth/sso/saml2/callback/{provider-id}. You must register this URL in your identity provider before SSO will work."
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://www.sim.ai/api/auth/sso/callback/{provider-id}. For SAML providers it is: https://www.sim.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?",
Expand Down