fix(scim): address the first review round and CI

- Filters accept unquoted booleans for active (RFC 7644)
- Group PATCH resolves order-sensitive membership deltas by last operation
  and refuses a non-string externalId
- Full writes accept case-insensitive attribute names (Entra's `username`)
- Credential issue counts and inserts under the connection row lock
- Projection records provenance only for access the directory actually
  granted unless the directory is the source of truth; skips departed
  members and workspaces moved to another organization
- Reconcile job verifies its lease per batch and reads settings after
  taking it
- Group writes serialize on the organization lock; the member role route
  runs its managed-membership check under the same locks
- Seat reconciliation targets the subscription admission validated against
- Docs: FAQ import, self-hosted flags; docs manifest regenerated
- Chart 1.10.0 for the new cron job; test fixtures carry column defaults

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: waleedlatif1

apps/docs/content/docs/platform/enterprise/scim.mdx

@@ -6,13 +6,14 @@ description: Create, update, and deactivate Sim members automatically from your
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { FAQ } from '@/components/ui/faq'
 
 Directory provisioning connects your identity provider to Sim over SCIM 2.0. Your provider creates members when someone joins, updates them when their details change, and deactivates them the moment they leave — without anyone touching Sim.
 
 It pairs with [SSO](/platform/enterprise/sso). SSO proves who someone is when they sign in. Directory provisioning decides who exists and what they can reach, before and after that.
 
 <Callout type="info">
-  Enterprise plans. Requires at least one [verified domain](/platform/enterprise/verified-domains) for your organization.
+  Enterprise plans. Requires at least one [verified domain](/platform/enterprise/verified-domains) for your organization. Self-hosted deployments turn it on with `SCIM_ENABLED=true` and `NEXT_PUBLIC_SCIM_ENABLED=true`, alongside the [SSO variables](/platform/enterprise/sso#self-hosted-setup).
 </Callout>
 
 ## What it does

apps/sim/app/api/organizations/[id]/members/[memberId]/route.ts

@@ -11,6 +11,7 @@ import { getSession } from '@/lib/auth'
 import { setActiveOrganizationForCurrentSession } from '@/lib/auth/active-organization'
 import { getOrganizationMemberUsageSnapshot } from '@/lib/billing/core/organization'
 import {
+  acquireOrganizationUserMutationLocks,
   removeExternalUserFromOrganizationWorkspaces,
   removeUserFromOrganization,
   WORKSPACE_BILLING_ACCOUNT_REMOVAL_ERROR,
@@ -214,24 +215,21 @@ export const PUT = withRouteHandler(
       }
 
       /**
-       * When the organization has made its identity provider the source of
-       * truth for membership, a role set here is reverted by the next sync.
-       * Refusing says so instead of letting the change quietly disappear.
+       * The member is re-read under the organization's mutation lock, so a
+       * concurrent promotion to owner — or a directory provisioning this very
+       * member — cannot slip between the checks and the write. When the
+       * organization has made its identity provider the source of truth, a role
+       * set here is reverted by the next sync; refusing says so.
        */
-      await assertMembershipNotScimManaged({
-        organizationId,
-        userId: memberId,
+      const roleChange = await db.transaction(async (tx) => {
+        await acquireOrganizationUserMutationLocks(tx, {
+          userId: memberId,
+          organizationIds: [organizationId],
+        })
+        await assertMembershipNotScimManaged({ organizationId, userId: memberId, executor: tx })
+        return changeMemberRoleTx(tx, { organizationId, userId: memberId, role })
       })
 
-      /**
-       * The shared primitive re-reads the member under the organization's
-       * mutation lock, so a concurrent promotion to owner cannot slip between
-       * the check above and the write.
-       */
-      const roleChange = await db.transaction((tx) =>
-        changeMemberRoleTx(tx, { organizationId, userId: memberId, role })
-      )
-
       /**
        * The audit row and analytics event fire whether or not the role actually
        * moved, exactly as this route did before the write went through the

apps/sim/ee/access-control/utils/permission-check.test.ts

@@ -83,7 +83,11 @@ function queueGroupResolution(
   workspaceGroups: WorkspaceGroupRow[] = [],
   defaultGroup: Array<{ config: Record<string, unknown> }> = []
 ) {
-  queueTableRows(permissionGroup, workspaceGroups)
+  /** Every row carries the column default the resolver reads, as a real row would. */
+  queueTableRows(
+    permissionGroup,
+    workspaceGroups.map((row) => ({ membershipMode: 'inherit', ...row }))
+  )
   queueTableRows(permissionGroup, defaultGroup)
 }
 

apps/sim/lib/api/contracts/scim.ts

@@ -7,7 +7,11 @@ import {
   SCIM_MAX_PATCH_OPERATIONS,
   SCIM_PATCH_OP_SCHEMA,
 } from '@/lib/scim/protocol/constants'
-import { normalizeScimBoolean, unwrapSingleElement } from '@/lib/scim/protocol/normalize'
+import {
+  canonicalizeAttributeNames,
+  normalizeScimBoolean,
+  unwrapSingleElement,
+} from '@/lib/scim/protocol/normalize'
 
 /**
  * Wire schemas for the SCIM 2.0 surface.
@@ -63,18 +67,32 @@ const scimEnterpriseSchema = z.looseObject({
  * keeps the credential out of the parsed request object and therefore out of
  * every log line and error detail downstream.
  */
-export const scimUserWriteSchema = z
-  .looseObject({
-    schemas: z.array(z.string().max(256)).min(1, 'schemas must name at least one URN').max(10),
-    userName: z.string().trim().min(1, 'userName must not be empty').max(320),
-    externalId: z.string().trim().max(256).optional(),
-    active: scimBoolean.optional(),
-    displayName: z.string().max(256).optional(),
-    name: scimNameSchema.optional(),
-    emails: z.array(scimEmailSchema).max(20).optional(),
-    [SCIM_ENTERPRISE_USER_SCHEMA]: scimEnterpriseSchema.optional(),
-  })
-  .transform(({ password: _password, ...rest }) => rest)
+const USER_WRITE_ATTRIBUTES = [
+  'schemas',
+  'userName',
+  'externalId',
+  'active',
+  'displayName',
+  'name',
+  'emails',
+  SCIM_ENTERPRISE_USER_SCHEMA,
+] as const
+
+export const scimUserWriteSchema = z.preprocess(
+  (body) => canonicalizeAttributeNames(body, USER_WRITE_ATTRIBUTES),
+  z
+    .looseObject({
+      schemas: z.array(z.string().max(256)).min(1, 'schemas must name at least one URN').max(10),
+      userName: z.string().trim().min(1, 'userName must not be empty').max(320),
+      externalId: z.string().trim().max(256).optional(),
+      active: scimBoolean.optional(),
+      displayName: z.string().max(256).optional(),
+      name: scimNameSchema.optional(),
+      emails: z.array(scimEmailSchema).max(20).optional(),
+      [SCIM_ENTERPRISE_USER_SCHEMA]: scimEnterpriseSchema.optional(),
+    })
+    .transform(({ password: _password, ...rest }) => rest)
+)
 /** What a client may send. */
 export type ScimUserWrite = z.input<typeof scimUserWriteSchema>
 /** What the route receives after parsing, which is what the canonicalizer reads. */
@@ -86,12 +104,17 @@ const scimGroupMemberSchema = z.looseObject({
   type: z.string().max(64).optional(),
 })
 
-export const scimGroupWriteSchema = z.looseObject({
-  schemas: z.array(z.string().max(256)).min(1, 'schemas must name at least one URN').max(10),
-  displayName: z.string().trim().min(1, 'displayName must not be empty').max(256),
-  externalId: z.string().trim().max(256).optional(),
-  members: z.array(scimGroupMemberSchema).max(SCIM_MAX_GROUP_MEMBERS).optional(),
-})
+const GROUP_WRITE_ATTRIBUTES = ['schemas', 'displayName', 'externalId', 'members'] as const
+
+export const scimGroupWriteSchema = z.preprocess(
+  (body) => canonicalizeAttributeNames(body, GROUP_WRITE_ATTRIBUTES),
+  z.looseObject({
+    schemas: z.array(z.string().max(256)).min(1, 'schemas must name at least one URN').max(10),
+    displayName: z.string().trim().min(1, 'displayName must not be empty').max(256),
+    externalId: z.string().trim().max(256).optional(),
+    members: z.array(scimGroupMemberSchema).max(SCIM_MAX_GROUP_MEMBERS).optional(),
+  })
+)
 export type ScimGroupWrite = z.input<typeof scimGroupWriteSchema>
 export type ScimGroupWriteParsed = z.output<typeof scimGroupWriteSchema>
 

apps/sim/lib/copilot/generated/docs-manifest.ts

@@ -375,6 +375,7 @@ export const DOCS_MANIFEST: readonly string[] = [
   'platform/enterprise/data-drains.mdx',
   'platform/enterprise/data-retention.mdx',
   'platform/enterprise/forks.mdx',
+  'platform/enterprise/scim.mdx',
   'platform/enterprise/self-hosted.mdx',
   'platform/enterprise/session-policies.mdx',
   'platform/enterprise/sso.mdx',

apps/sim/lib/core/config/deployment-shape.test.ts

@@ -36,6 +36,7 @@ describe('resolveDeploymentShape', () => {
         dataRetention: false,
         inbox: true,
         sandboxes: true,
+        scim: false,
         sessionPolicies: true,
         sso: true,
         usageMonitoring: false,

apps/sim/lib/scim/application/admin/credentials.ts

@@ -34,43 +34,52 @@ export const issueScimCredential = defineAuthorizedScimAdminUseCase({
   operation: scimAdminOperations.issueCredential,
   async execute({ input, context }: ScimAdminUseCaseArgs<IssueScimCredentialInput>) {
     const connection = await requireConnection(context.organizationId)
-
-    const [active] = await db
-      .select({ value: count() })
-      .from(scimCredential)
-      .where(activeCredentialCondition(connection.id))
-    if ((active?.value ?? 0) >= MAX_ACTIVE_CREDENTIALS) {
-      throw new OrchestrationError(
-        'conflict',
-        `At most ${MAX_ACTIVE_CREDENTIALS} credentials may be active at once. Revoke one before issuing another.`
-      )
-    }
-
     const { secret, hash, prefix } = generateScimToken()
     const scopes = input.scopes ?? [...SCIM_SCOPES]
     const expiresAt = input.expiresInDays
       ? new Date(Date.now() + input.expiresInDays * DAY_MS)
       : null
 
-    const [created] = await db
-      .insert(scimCredential)
-      .values({
-        id: generateId(),
-        connectionId: connection.id,
-        tokenHash: hash,
-        tokenPrefix: prefix,
-        scopes,
-        expiresAt,
-        createdBy: context.actorUserId,
-      })
-      .returning({
-        id: scimCredential.id,
-        tokenPrefix: scimCredential.tokenPrefix,
-        scopes: scimCredential.scopes,
-        expiresAt: scimCredential.expiresAt,
-        lastUsedAt: scimCredential.lastUsedAt,
-        createdAt: scimCredential.createdAt,
-      })
+    const created = await db.transaction(async (tx) => {
+      /** The connection row is the lock, so two issue requests cannot both see one free slot. */
+      await tx
+        .select({ id: scimConnection.id })
+        .from(scimConnection)
+        .where(eq(scimConnection.id, connection.id))
+        .for('update')
+
+      const [active] = await tx
+        .select({ value: count() })
+        .from(scimCredential)
+        .where(activeCredentialCondition(connection.id))
+      if ((active?.value ?? 0) >= MAX_ACTIVE_CREDENTIALS) {
+        throw new OrchestrationError(
+          'conflict',
+          `At most ${MAX_ACTIVE_CREDENTIALS} credentials may be active at once. Revoke one before issuing another.`
+        )
+      }
+
+      const [row] = await tx
+        .insert(scimCredential)
+        .values({
+          id: generateId(),
+          connectionId: connection.id,
+          tokenHash: hash,
+          tokenPrefix: prefix,
+          scopes,
+          expiresAt,
+          createdBy: context.actorUserId,
+        })
+        .returning({
+          id: scimCredential.id,
+          tokenPrefix: scimCredential.tokenPrefix,
+          scopes: scimCredential.scopes,
+          expiresAt: scimCredential.expiresAt,
+          lastUsedAt: scimCredential.lastUsedAt,
+          createdAt: scimCredential.createdAt,
+        })
+      return row
+    })
 
     return { secret, credential: toCredentialView(created), connectionId: connection.id }
   },

apps/sim/lib/scim/application/groups/manage-groups.ts

@@ -3,6 +3,7 @@ import { db } from '@sim/db'
 import { scimGroup } from '@sim/db/schema'
 import { and, eq, ne } from 'drizzle-orm'
 import type { ScimPatchOperation } from '@/lib/api/contracts/scim'
+import { acquireOrganizationMutationLock } from '@/lib/billing/organizations/membership'
 import type { DbOrTx } from '@/lib/db/types'
 import {
   defineAuthorizedScimUseCase,
@@ -164,6 +165,12 @@ export const createScimGroup = defineAuthorizedScimUseCase({
   }: ScimUseCaseArgs<CreateScimGroupInput>): Promise<ScimGroupWriteResult> {
     const { group } = input
     return db.transaction(async (tx) => {
+      /**
+       * Group writes serialize on the organization lock, which also heads the
+       * documented lock order, so two full-membership PATCHes cannot both compute
+       * from the same stale membership and keep members from both.
+       */
+      await acquireOrganizationMutationLock(tx, context.organizationId)
       await assertDisplayNameAvailable(tx, {
         connectionId: context.connection.id,
         displayName: group.displayName,
@@ -226,6 +233,12 @@ export const replaceScimGroup = defineAuthorizedScimUseCase({
     context,
   }: ScimUseCaseArgs<ReplaceScimGroupInput>): Promise<ScimGroupWriteResult> {
     return db.transaction(async (tx) => {
+      /**
+       * Group writes serialize on the organization lock, which also heads the
+       * documented lock order, so two full-membership PATCHes cannot both compute
+       * from the same stale membership and keep members from both.
+       */
+      await acquireOrganizationMutationLock(tx, context.organizationId)
       const current = await findScimGroupById(tx, context.connection.id, input.groupId)
       if (!current) throw notFound('SCIM Group not found')
 
@@ -321,6 +334,12 @@ export const patchScimGroup = defineAuthorizedScimUseCase({
     const patch = parseGroupPatch(input.operations)
 
     return db.transaction(async (tx) => {
+      /**
+       * Group writes serialize on the organization lock, which also heads the
+       * documented lock order, so two full-membership PATCHes cannot both compute
+       * from the same stale membership and keep members from both.
+       */
+      await acquireOrganizationMutationLock(tx, context.organizationId)
       const current = await findScimGroupById(tx, context.connection.id, input.groupId)
       if (!current) throw notFound('SCIM Group not found')
 
@@ -431,6 +450,12 @@ export const deleteScimGroup = defineAuthorizedScimUseCase({
   operation: scimOperations.deleteGroup,
   async execute({ input, context }: ScimUseCaseArgs<DeleteScimGroupInput>) {
     return db.transaction(async (tx) => {
+      /**
+       * Group writes serialize on the organization lock, which also heads the
+       * documented lock order, so two full-membership PATCHes cannot both compute
+       * from the same stale membership and keep members from both.
+       */
+      await acquireOrganizationMutationLock(tx, context.organizationId)
       const current = await findScimGroupById(tx, context.connection.id, input.groupId)
       if (!current) throw notFound('SCIM Group not found')
 

apps/sim/lib/scim/application/users/provision-user.ts

@@ -53,6 +53,8 @@ export interface ProvisionScimUserResult {
   createdAccount: boolean
   /** False when the account was already a member and only the SCIM link was new. */
   joinedOrganization: boolean
+  /** The subscription seats were validated against, so the post-commit seat sync targets the same one. */
+  subscriptionId: string | undefined
   organizationId: string
   resource: ReturnType<typeof toUserResource>
 }
@@ -179,7 +181,11 @@ export const provisionScimUser = defineAuthorizedScimUseCase({
       await deleteScimUser(db, existing.id)
     }
 
-    let provisioned: { scimUserId: string; joinedOrganization: boolean }
+    let provisioned: {
+      scimUserId: string
+      joinedOrganization: boolean
+      subscriptionId: string | undefined
+    }
     try {
       provisioned = await db.transaction(async (tx) => {
         const seatPolicy = await resolveSeatPolicy(tx, context.organizationId)
@@ -231,7 +237,11 @@ export const provisionScimUser = defineAuthorizedScimUseCase({
           scimUserId: inserted.id,
           settings: context.connection.settings,
         })
-        return { scimUserId: inserted.id, joinedOrganization: !membership.alreadyMember }
+        return {
+          scimUserId: inserted.id,
+          joinedOrganization: !membership.alreadyMember,
+          subscriptionId: seatPolicy.organizationSubscriptionId,
+        }
       })
     } catch (error) {
       /**
@@ -253,7 +263,7 @@ export const provisionScimUser = defineAuthorizedScimUseCase({
       }
       throw error
     }
-    const { scimUserId, joinedOrganization } = provisioned
+    const { scimUserId, joinedOrganization, subscriptionId } = provisioned
 
     const record = await findScimUserById(db, context.connection.id, scimUserId)
     if (!record) throw new ScimError(500, undefined, 'The provisioned user could not be read back')
@@ -263,6 +273,7 @@ export const provisionScimUser = defineAuthorizedScimUseCase({
       userId,
       createdAccount,
       joinedOrganization,
+      subscriptionId,
       organizationId: context.organizationId,
       resource: toUserResource(toUserResourceRow(record, []), context.baseUrl),
     }
@@ -303,6 +314,8 @@ export const provisionScimUser = defineAuthorizedScimUseCase({
       await reconcileOrganizationSeats({
         organizationId: context.organizationId,
         reason: 'scim-member-added',
+        /** The subscription admission was validated against, not whichever is newest now. */
+        ...(result.subscriptionId ? { subscriptionId: result.subscriptionId } : {}),
       })
     } catch (error) {
       logger.error('Failed to reconcile seats after directory provisioning', { error })