fix(sso): link Entra sign-ins to existing accounts and enforce unique provider IDs

Better Auth 1.6.23 calls the account-linking handler with trustProviderByName:
false, which disables the trustedProviders allowlist for SSO entirely. Trust now
comes only from the provider's domainVerified flag, which Sim never set — so any
user who already had a Sim account was stranded on "account not linked". Entra
never sends email_verified, so this hit every Microsoft tenant.

Sim already proves domain ownership via sso_domain before a provider can be
registered, so the register route mirrors that decision onto domainVerified.
The column defaults to true so existing providers keep signing in across the
deploy, since enabling the option turns sign-in into a hard gate.

Also enforces the providerId uniqueness Better Auth already assumes: it rejects
any id that exists in any tenant and resolves providers by that column alone, so
a second customer picking "azure-ad" could not register at all and got an opaque
422. Sim now returns a 409 naming a free id, and a unique index makes the
duplicate-row state unreachable.

Author: waleedlatif1

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

@@ -12,11 +12,21 @@ Single Sign-On lets your team sign in to Sim through your company's identity pro
 
 ---
 
+## Before you start
+
+<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.
+</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.
+
+---
+
 ## Setup
 
 ### 1. Open SSO settings
 
-Go to **Settings → Enterprise → Single Sign-On** in your workspace.
+Go to **Settings → Security → Single sign-on** in your organization settings.
 
 ### 2. Choose a protocol
 
@@ -33,7 +43,7 @@ Go to **Settings → Enterprise → Single Sign-On** in your workspace.
 
 | Field | What to enter |
 |-------|--------------|
-| **Provider ID** | A short slug identifying this connection, e.g. `okta` or `azure-ad`. Letters, numbers, and dashes only. |
+| **Provider ID** | A short slug identifying this connection. Letters, numbers, and dashes only. It must be **unique across every Sim organization**, so include something specific to you — `azure-ad-acme`, not `azure-ad`. If the ID is taken, Sim tells you and suggests a free one. |
 | **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. |
 
@@ -118,19 +128,21 @@ The issuer URL uses Okta's default authorization server, which is pre-configured
 **In Azure** ([official docs](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)):
 
 1. Go to **Microsoft Entra ID → App registrations → New registration**
-2. Under **Redirect URI**, select **Web** and enter your Sim callback URL:
+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
+   https://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**
+5. Go to **Token configuration → Add optional claim**, choose **ID**, and add **email**. Entra omits the email address for managed users without this claim, and sign-in then fails with a missing-user-info error
+6. If **Enterprise applications → Sim → Properties → Assignment required** is **Yes**, assign the users or groups who should sign in. Microsoft rejects unassigned users before they reach Sim
 
 **In Sim:**
 
 | Field | Value |
 |-------|-------|
 | Provider Type | OIDC |
-| Provider ID | `azure-ad` |
+| Provider ID | `azure-ad-acme` (must be globally unique) |
 | Issuer URL | `https://login.microsoftonline.com/{tenant-id}/v2.0` |
 | Domain | `company.com` |
 | Client ID | Application (client) ID |
@@ -252,7 +264,7 @@ 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 the existing account automatically, as long as your identity provider reports the email as verified (email_verified) or the provider is trusted. Most OIDC providers (Okta, Google Workspace, Auth0) assert email_verified, so linking just works. If sign-in fails with 'account not linked' — common with SAML providers that omit the claim — add the provider's ID to SSO_TRUSTED_PROVIDER_IDS on self-hosted and restart."
+    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."
   },
   {
     question: "Who can configure SSO on Sim Cloud?",
@@ -264,7 +276,7 @@ SSO provisioning creates internal organization members. External workspace membe
   },
   {
     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."
+    answer: "Open Settings → Security → Single sign-on and click Edit. Update the fields and save. The existing provider configuration is replaced."
   }
 ]} />
 
@@ -285,22 +297,18 @@ NEXT_PUBLIC_SSO_ENABLED=true
 ORGANIZATIONS_ENABLED=true
 NEXT_PUBLIC_ORGANIZATIONS_ENABLED=true
 
-# Optional: comma-separated SSO provider IDs to trust for automatic account linking
-# (links an SSO sign-in to an existing account with the same email). Needed when your
-# IdP does not assert email_verified — typically SAML providers, or OIDC providers that
-# omit the claim. Set it to the Provider ID you registered, then restart.
-# (If you also keep SSO_PROVIDER_ID in the app's environment, that provider is trusted
-# without listing it here.)
+# Optional: comma-separated provider IDs to trust for automatic account linking.
+# This applies to non-SSO providers only — SSO linking is authorized by the
+# verified domain on the provider itself, not by this list.
 SSO_TRUSTED_PROVIDER_IDS=custom-oidc,partner-saml
 ```
 
 <Callout type="info">
   When someone signs in with SSO and an account with the same email already exists
   (for example, they previously signed up with email/password), Sim links the SSO
-  identity to that account automatically as long as your IdP reports the email as
-  verified, or the provider is trusted. If you hit an `account not linked` error,
-  either confirm your IdP sends `email_verified`, or add the provider's ID to
-  `SSO_TRUSTED_PROVIDER_IDS` and restart.
+  identity to that account automatically. That linking is authorized by the verified
+  domain attached to the provider, so it works for both OIDC and SAML and does not
+  depend on your IdP asserting `email_verified`.
 </Callout>
 
 You can register providers through the **Settings UI** (same as cloud) or by running the registration script directly against your database.

apps/sim/app/api/auth/sso/register/route.test.ts

@@ -39,12 +39,19 @@ function queueMembers(rows: Array<Record<string, unknown>>) {
 }
 
 /**
- * Queues existing SSO provider rows for BOTH domain-conflict lookups (the
- * pre-registration check and the post-registration re-check).
+ * Queues the sso_provider lookups a registration performs, in route order:
+ * providerId conflict then domain conflict, once before OIDC discovery and again
+ * immediately before the write. `providerIdRows` defaults to empty so
+ * domain-conflict tests are unaffected by the providerId check.
  */
-function queueProviders(rows: Array<Record<string, unknown>>) {
-  queueTableRows(schemaMock.ssoProvider, rows)
-  queueTableRows(schemaMock.ssoProvider, rows)
+function queueProviders(
+  domainRows: Array<Record<string, unknown>>,
+  providerIdRows: Array<Record<string, unknown>> = []
+) {
+  queueTableRows(schemaMock.ssoProvider, providerIdRows)
+  queueTableRows(schemaMock.ssoProvider, domainRows)
+  queueTableRows(schemaMock.ssoProvider, providerIdRows)
+  queueTableRows(schemaMock.ssoProvider, domainRows)
 }
 
 vi.mock('@/lib/auth', () => ({
@@ -214,6 +221,73 @@ describe('POST /api/auth/sso/register', () => {
     expect(mockRegisterSSOProvider).toHaveBeenCalledTimes(1)
   })
 
+  /**
+   * Better Auth scopes providerId uniqueness globally, not per tenant, and would
+   * otherwise reject this with an opaque 422 that reads like a bug. Sim catches
+   * it first and returns a 409 naming a free id.
+   */
+  it('rejects a providerId already taken by another organization', async () => {
+    queueMembers([{ organizationId: 'org-b', role: 'owner' }])
+    queueProviders([], [{ domain: 'other.com', userId: 'u-other', organizationId: 'org-other' }])
+    const res = await POST(request({ ...OIDC_BODY, orgId: 'org-b' }))
+    const json = await res.json()
+    expect(res.status).toBe(409)
+    expect(json.code).toBe('SSO_PROVIDER_ID_TAKEN')
+    expect(mockRegisterSSOProvider).not.toHaveBeenCalled()
+  })
+
+  it('suggests a free, domain-scoped providerId when the requested one is taken', async () => {
+    queueMembers([{ organizationId: 'org-b', role: 'owner' }])
+    queueProviders([], [{ domain: 'other.com', userId: 'u-other', organizationId: 'org-other' }])
+    const res = await POST(request({ ...OIDC_BODY, orgId: 'org-b' }))
+    const json = await res.json()
+    expect(json.error).toContain('acme-oidc-acme')
+  })
+
+  it('does not treat the caller’s own provider as a providerId conflict', async () => {
+    queueMembers([{ organizationId: 'org1', role: 'owner' }])
+    queueProviders([], [{ domain: 'acme.com', userId: 'u1', organizationId: 'org1' }])
+    const res = await POST(request({ ...OIDC_BODY, orgId: 'org1' }))
+    expect(res.status).toBe(200)
+  })
+
+  /**
+   * Better Auth's `isTrustedProvider` reads this flag, and it is the only thing
+   * that lets an SSO sign-in link to a pre-existing same-email account once the
+   * plugin stopped honouring `trustedProviders` for SSO. `registerSSOProvider`
+   * always persists `false`, so the route must set it after the write.
+   */
+  it('marks the provider domain-verified after registering', async () => {
+    queueMembers([{ organizationId: 'org1', role: 'owner' }])
+    const res = await POST(request({ ...OIDC_BODY, orgId: 'org1' }))
+    expect(res.status).toBe(200)
+    expect(dbChainMockFns.set).toHaveBeenCalledWith({ domainVerified: true })
+  })
+
+  /** updateSSOProvider resets domainVerified to false whenever the domain changes. */
+  it('re-marks the provider domain-verified after an update', async () => {
+    queueMembers([{ organizationId: 'org1', role: 'owner' }])
+    queueProviders([])
+    queueTableRows(schemaMock.ssoProvider, [{ id: 'p1' }])
+    const res = await POST(request({ ...OIDC_BODY, orgId: 'org1' }))
+    expect(res.status).toBe(200)
+    expect(mockUpdateSSOProvider).toHaveBeenCalledTimes(1)
+    expect(dbChainMockFns.set).toHaveBeenCalledWith({ domainVerified: true })
+  })
+
+  it('does not mark domain-verified when the registration is rolled back', async () => {
+    queueMembers([{ organizationId: 'org1', role: 'owner' }])
+    resetDbChainMock()
+    queueMembers([{ organizationId: 'org1', role: 'owner' }])
+    // Verified for both pre-write gates, then revoked for the post-write re-check.
+    queueTableRows(schemaMock.ssoDomain, [{ id: 'verified-domain' }])
+    queueTableRows(schemaMock.ssoDomain, [{ id: 'verified-domain' }])
+    queueTableRows(schemaMock.ssoDomain, [])
+    const res = await POST(request({ ...OIDC_BODY, orgId: 'org1' }))
+    expect(res.status).toBe(403)
+    expect(dbChainMockFns.set).not.toHaveBeenCalledWith({ domainVerified: true })
+  })
+
   it('nests the attribute mapping inside oidcConfig (Better Auth reads it there)', async () => {
     queueMembers([{ organizationId: 'org1', role: 'owner' }])
     await POST(
@@ -227,8 +301,7 @@ describe('POST /api/auth/sso/register', () => {
 
   it('routes an edit of an existing owned provider through updateSSOProvider', async () => {
     queueMembers([{ organizationId: 'org1', role: 'owner' }])
-    queueTableRows(schemaMock.ssoProvider, []) // findDomainConflict #1 → no conflict
-    queueTableRows(schemaMock.ssoProvider, []) // findDomainConflict #2 → no conflict
+    queueProviders([]) // no providerId or domain conflicts on either pass
     queueTableRows(schemaMock.ssoProvider, [{ id: 'p1' }]) // provider already owned → edit
     const res = await POST(request({ ...OIDC_BODY, orgId: 'org1' }))
     expect(res.status).toBe(200)

apps/sim/app/api/auth/sso/register/route.ts

@@ -40,6 +40,18 @@ function selectTokenEndpointAuthMethod(
   return 'client_secret_post'
 }
 
+/**
+ * Proposes a free, tenant-scoped provider ID by suffixing the domain's first
+ * label (`azure-ad` + `acme.com` -> `azure-ad-acme`), so a caller who hit the
+ * global-uniqueness collision is handed something concrete to type rather than
+ * being asked to invent a name. Callers pass a domain that already went through
+ * `normalizeSSODomain`, whose `^[a-z0-9-]+(\.[a-z0-9-]+)+$` shape guarantees a
+ * non-empty first label needing no further sanitizing.
+ */
+function suggestProviderId(providerId: string, domain: string): string {
+  return `${providerId}-${domain.split('.')[0]}`
+}
+
 type DiscoveryResult =
   | { ok: true; discovery: Record<string, unknown> }
   | { ok: false; error: string }
@@ -187,6 +199,43 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
         { status: 409 }
       )
 
+    /**
+     * Better Auth treats `providerId` as globally unique, not per-tenant:
+     * `registerSSOProvider` rejects any id already present regardless of owner,
+     * and `checkProviderAccess` resolves providers by that column alone. Catch
+     * the cross-tenant collision here so the caller gets an actionable 409 that
+     * names a free id, instead of Better Auth's opaque 422 ("SSO provider with
+     * this providerId already exists") that gives no hint anything can be done.
+     */
+    const findProviderIdConflict = async () =>
+      (
+        await db
+          .select({
+            userId: ssoProvider.userId,
+            organizationId: ssoProvider.organizationId,
+          })
+          .from(ssoProvider)
+          .where(eq(ssoProvider.providerId, providerId))
+      ).find((provider) => !isOwnedByCaller(provider))
+
+    const providerIdConflictResponse = () =>
+      NextResponse.json(
+        {
+          error: `The provider ID "${providerId}" is already taken by another organization. Provider IDs are global, so pick a unique one — for example "${suggestProviderId(providerId, domain)}". It appears in the redirect URL you register with your identity provider, so choose it before configuring the IdP.`,
+          code: 'SSO_PROVIDER_ID_TAKEN',
+        },
+        { status: 409 }
+      )
+
+    if (await findProviderIdConflict()) {
+      logger.warn('Rejected SSO registration for providerId owned by another tenant', {
+        providerId,
+        orgId,
+        userId: session.user.id,
+      })
+      return providerIdConflictResponse()
+    }
+
     if (await findDomainConflict()) {
       logger.warn('Rejected SSO registration for domain owned by another tenant', {
         domain,
@@ -537,6 +586,15 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       ),
     })
 
+    if (await findProviderIdConflict()) {
+      logger.warn('Rejected SSO registration: providerId was claimed during registration', {
+        providerId,
+        orgId,
+        userId: session.user.id,
+      })
+      return providerIdConflictResponse()
+    }
+
     if (await findDomainConflict()) {
       logger.warn('Rejected SSO registration: domain was claimed during registration', {
         domain,
@@ -584,6 +642,20 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       .where(ownerClause)
       .limit(1)
 
+    /**
+     * Mirrors Sim's own domain-ownership proof onto Better Auth's `domainVerified`
+     * flag, which is what lets an SSO sign-in auto-link to an existing same-email
+     * account. Must run after every write, not just on create: `registerSSOProvider`
+     * always persists `false`, and `updateSSOProvider` resets it to `false` whenever
+     * the domain changes. Only ever called once the verification gate above has
+     * passed for this exact domain, so it can never mark an unproven domain as
+     * verified. Org-less (personal) SSO is not domain-gated by Sim and keeps its
+     * pre-existing trust here, matching how it behaved before the flag existed.
+     */
+    const markProviderDomainVerified = async () => {
+      await db.update(ssoProvider).set({ domainVerified: true }).where(ownerClause)
+    }
+
     if (existingOwnedProvider) {
       await auth.api.updateSSOProvider({
         body: {
@@ -595,6 +667,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
         },
         headers,
       })
+      await markProviderDomainVerified()
       logger.info('SSO provider updated successfully', { providerId, providerType, domain })
       return NextResponse.json({
         success: true,
@@ -644,6 +717,8 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       return domainNotVerifiedResponse()
     }
 
+    await markProviderDomainVerified()
+
     logger.info('SSO provider registered successfully', {
       providerId,
       providerType,

apps/sim/ee/sso/components/sso-settings.tsx

@@ -516,6 +516,10 @@ function OrganizationSsoSettings({ organizationId }: SSOProps) {
                 placeholder='Select or enter a provider ID'
                 editable
               />
+              <p className='text-[var(--text-muted)] text-small'>
+                Must be unique across all Sim organizations — include something specific to you,
+                like <span className='font-mono'>azure-ad-acme</span>.
+              </p>
             </SettingRow>
 
             <SettingRow