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

[waleedlatif1]

Summary

Corrections and gaps found while walking a live customer through SAML setup. Every claim below was verified against the code or against the working provider row in production, not assumed.

Incorrect guidance, now fixed

• Callback URLs printed https://sim.ai/... while the app emits https://www.sim.ai/.... Identity providers match these character for character, so following the docs instead of copying from the settings page produced a 404 after authentication.
• The ADFS tab told users to set Issuer URL to Sim's own URL. That field is the identity provider's identifier — with no IdP metadata, createSP/createIdP fall back to it as the IdP entity ID (idpData?.entityID || config.issuer). The working Entra provider in production confirms the intended shape: its issuer is the IdP's sts.windows.net/{tenant}/, not Sim's URL. Sim's own identifier is the separate SP Entity ID field.
• Sim's form requires an https issuer, but ADFS commonly defaults its Federation Service identifier to http://. Noted, since the previous example would have been rejected on save.
• Provider ID was described as changeable ("changing it later means redoing that step"). It is read-only once saved.

Missing, now documented

• A SAML guide for Microsoft Entra. SAML was only covered for ADFS, yet Entra + SAML is what a customer just configured. Values are taken from the working provider row.
• IdP-initiated sign-in is rejected. Launching from Microsoft My Apps or an Okta tile sends an unsolicited assertion, which we refuse by design. Testing must start from Sim. Without this, a correct configuration looks broken.
• Linking matches on the exact email address. If the IdP asserts a different address than the existing account — a privileged variant like p-alice@company.com, or an alias — a second account is created instead of linking. Observed live today.
• Removing a verified domain immediately disables SSO for that domain until it is verified again.

Type of Change

• Bug fix (documentation)

Testing

Docs-only. fumadocs-mdx compiles the content cleanly ([MDX] generated files in 34ms); the next build step then fails on a missing DATABASE_URL in this environment, which is unrelated to content. Verified no sim.ai/api/auth occurrence remains without the www. host, that no other page under apps/docs/content references these endpoints, and that the Tab/Tabs tags balance (5 and 5) after adding the new tab.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[waleedlatif1]

@greptile

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 6, 2026 7:02pm

[cursor]

PR Summary

Low Risk
Documentation-only changes to enterprise SSO guidance; no application code or runtime behavior is modified.

Overview
Updates enterprise SSO documentation so IdP configuration matches what Sim Cloud actually emits and how SAML fields are interpreted.

Callback URLs now use https://www.sim.ai/... everywhere (OIDC and SAML examples, provider tabs, FAQ). The previous sim.ai host caused post-auth 404s when admins registered the wrong redirect URI.

SAML field guidance is corrected: Issuer URL is documented as the identity provider’s identifier (e.g. Entra sts.windows.net, ADFS federation service trust URI), not Sim’s URL; relying-party / SP Entity ID is separate. ADFS steps point SP Entity ID at Sim’s SP Entity ID field and note the https issuer requirement when ADFS defaults to http.

New coverage includes a Microsoft Entra ID (SAML) provider tab, a warning that IdP-initiated sign-in (My Apps / Okta tiles) is rejected and tests must start from Sim, that removing a verified domain disables SSO for that domain until re-verified, that Provider ID is fixed after save, and FAQ detail on exact email matching for account linking.

^{Reviewed by Cursor Bugbot for commit fde9e82. Configure here.}

[waleedlatif1]

@cursor review

[greptile-apps]

Greptile Summary

The SSO documentation corrects callback hosts and provider-field guidance while adding Microsoft Entra SAML setup and sign-in behavior details.

• Uses www.sim.ai consistently for OIDC and SAML callback URLs.
• Documents Entra SAML configuration, ADFS issuer semantics, exact-email account linking, verified-domain removal behavior, and the requirement to initiate sign-in from Sim.
• Correctly directs Entra Federation Metadata XML to the optional IDP Metadata XML field while retaining the required certificate.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/docs/content/docs/en/platform/enterprise/sso.mdx	Updates SSO endpoint and provider guidance and fully resolves the prior ambiguity between Entra metadata and certificate fields.

_{Reviews (2): Last reviewed commit: "docs(sso): send Entra federation metadat..." | Re-trigger Greptile}

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit bf5d39d. Configure here.}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit fde9e82. Configure here.}