Provision organization groups and sub-organizations from IdP directory data

[jrf0110]

Summary

Allow enterprise organization administrators to provision and deprovision Kilo organization membership, sub-organization membership, and organization-group membership from their identity provider (IdP).

Administrators should be able to connect an IdP directory through WorkOS Directory Sync and explicitly map IdP directory groups or normalized user attributes to Kilo destinations. Kilo should continuously reconcile those mappings as directory users and groups change, without requiring manual assignment or waiting for the affected user to log in.

This is a complete user-lifecycle-management feature, not only login-time SSO attribute mapping. Login-time claims may help resolve identity, but they cannot be the source of truth because they do not reliably handle users who never log in again, deactivation, group removal, missed events, or changes made while a user is offline.

Why

Enterprise administrators commonly manage application access centrally in Okta, Microsoft Entra ID, Google Workspace, or another directory. Today they must repeat organizational assignments manually in Kilo. This creates administrative overhead and allows Kilo access to drift from the IdP when employees join, transfer, or leave.

The desired experience is:

An administrator maps IdP groups or directory attributes to Kilo groups and sub-organizations once. Kilo then keeps directory-managed assignments synchronized while preserving unrelated manual and elevated access.

Terminology

• SSO authenticates a user. It proves who is signing in but does not provide complete offline lifecycle management.
• Directory Sync is WorkOS's user-lifecycle-management layer. Depending on the customer's provider, WorkOS may use SCIM or a provider-specific directory integration behind the scenes.
• Directory user/group is the WorkOS representation of an IdP user/group.
• Kilo organization group is a policy-bearing group inside one Kilo organization.
• Sub-organization is a direct child Kilo organization with its own direct memberships, roles, data, and resources.
• Managed entitlement is an organization or group assignment justified by an active directory mapping.
• Manual entitlement is access explicitly granted in Kilo independently of directory mappings.
• Suppression is an explicit Kilo-side decision not to restore a directory-desired assignment until an administrator clears the suppression.

Existing behavior and extension points

These links capture relevant behavior at commit a9adfa9:

• WorkOS is currently configured as a NextAuth SSO provider: apps/web/src/lib/user/server.ts#L656-L662.
• The SSO profile is reduced to basic identity fields; IdP group/custom-attribute data is not consumed: apps/web/src/lib/user/server.ts#L328-L345.
• Successful SSO currently performs just-in-time membership admission into the SSO authority organization: apps/web/src/lib/user/sso.ts#L20-L125.
• Organizations can be direct children of another organization: packages/db/src/schema.ts#L2910-L2958.
• Direct organization membership, organization groups, and group membership are separate concepts: packages/db/src/schema.ts#L3470-L3566.
• Group membership currently requires direct membership in the same organization: packages/db/src/schema.ts#L3532-L3558.
• Manual group assignment replaces the selected member's group set and records audit activity: apps/web/src/lib/organizations/organization-groups.ts#L622-L705.
• Membership removal records durable removal state and invalidates derived access: apps/web/src/lib/organizations/organizations.ts#L403-L496.
• Existing SSO administration already uses the WorkOS organization and Admin Portal: apps/web/src/routers/organizations/organization-sso-router.ts#L51-L204.

There is currently no WorkOS Directory Sync ingestion, directory-user identity mapping, provisioning-rule configuration, or IdP-driven deprovisioning.

Goals

• Let an authorized parent-organization administrator enable and inspect Directory Sync through WorkOS.
• Support IdP directory groups and normalized/custom directory-user attributes as mapping sources.
• Support the parent organization, direct sub-organizations, and Kilo organization groups as explicit mapping targets.
• Apply changes without requiring the affected user to sign in.
• Provision users who have not yet used Kilo without creating a non-SSO authentication path.
• Deprovision directory-managed access promptly when the directory removes or deactivates a user.
• Preserve manually managed access and elevated sub-organization roles.
• Make synchronization idempotent, observable, auditable, and repairable after missed or out-of-order events.
• Support a safe preview and staged rollout before a mapping becomes authoritative.

Non-goals

• Building and maintaining a public SCIM server when WorkOS Directory Sync can normalize provider behavior.
• Automatically creating, renaming, or deleting Kilo organizations or Kilo organization groups based on IdP objects.
• Automatically granting owner, admin, or billing_manager roles from an IdP attribute. Provisioned organization memberships use member unless a separate future feature explicitly introduces safe role mapping.
• Automatically matching Kilo targets by mutable display name.
• Importing or retaining arbitrary raw IdP payloads that are not needed for configured mappings, support, or auditability.
• Changing authentication requirements for external users or service/bot accounts.
• Treating parent access, child membership, and organization-group membership as interchangeable.

Product requirements

1. Directory setup and ownership

• Directory Sync is configured for the same WorkOS organization that acts as the Kilo parent organization's SSO authority.
• Only an authorized parent-organization administrator or platform administrator can enable, disable, or configure directory provisioning.
• The administration surface shows directory provider/type, connection state, last successful event, last successful reconciliation, and actionable errors.
• Directory setup uses the WorkOS Admin Portal where possible so customer administrators can configure their provider without Kilo handling provider credentials.
• A directory cannot control an unrelated Kilo organization hierarchy.
• Replacing or deleting a directory requires an impact preview and explicit confirmation of how existing managed entitlements will be handled.

2. Mapping sources

An administrator can configure a rule using either:

• membership in a specific WorkOS directory group, selected by immutable directory-group identity; or
• an equality/membership match against an allowed normalized or custom directory-user attribute, such as department, division, cost center, organization, or a customer-mapped field.

Source requirements:

• Attribute keys available for mapping are explicitly allowlisted/configured. The UI does not accept arbitrary object traversal or executable expressions.
• Rules support scalar and multi-valued string attributes with documented matching and normalization behavior.
• Matching is exact after normalization. Case sensitivity and whitespace normalization are visible and deterministic.
• Missing, null, malformed, or unsupported values do not match and are surfaced in preview/diagnostics rather than guessed.
• Group mappings use immutable WorkOS IDs even if a group is renamed.
• Deleted source groups make their mappings invalid and visible; they do not silently retarget a same-named replacement.

3. Mapping targets

A rule can target one or more explicitly selected destinations within the parent hierarchy:

• direct membership in the parent organization;
• direct member membership in one or more direct sub-organizations; and/or
• membership in one or more Kilo organization groups.

Target requirements:

• Targets are stored by immutable Kilo ID, not name.
• Only the parent and its direct, active sub-organizations are eligible. Recursive descendants, siblings, deleted organizations, and unrelated organizations are rejected.
• A Kilo organization group target must belong to an eligible target organization.
• Because organization-group membership requires direct organization membership, the configuration and preview must make prerequisite membership explicit. A group target must either include/derive direct membership in its owning organization or remain blocked until that direct membership exists; it must never create an implicit, undisclosed organization membership.
• Provisioned organization membership always starts as member.
• A mapping cannot create, downgrade, replace, or remove an elevated role.

4. Preview, activation, and mapping lifecycle

Before activation, an administrator can preview:

• users who would gain or lose each organization/group assignment;
• users who cannot be linked to a Kilo identity;
• seat/capacity conflicts;
• elevated roles that will be protected;
• manual grants that will be preserved;
• explicit suppressions that prevent restoration;
• deleted/invalid targets or sources; and
• the downstream cleanup implications of removals.

Mapping states and actions:

• Draft: editable and has no effect.
• Active: contributes to desired entitlement state and is continuously reconciled.
• Paused: stops processing changes and preserves currently applied entitlements. The UI clearly warns that access may drift while paused.
• Delete/unmap: previews and, after confirmation, removes only entitlements solely justified by that mapping. Shared or manual entitlements remain.
• Material mapping changes use the same preview-and-confirm flow as activation.

5. Identity lifecycle and linking

• Directory identity is tracked using immutable WorkOS directory and directory-user identifiers. Email is not the durable external identity key.
• An active directory user can be provisioned before first login.
• If no Kilo account exists, Kilo creates or records a dormant directory-provisioned identity sufficient to hold desired memberships. It does not create a password, magic-link exemption, personal access path, or any other way around SSO.
• On first SSO login, the account is linked to the directory identity and retains its already-provisioned entitlements.
• An existing Kilo user may be linked automatically only when the email relationship is unambiguous and has been verified through the matching WorkOS authority. Ambiguous, duplicate, conflicting-domain, or already-linked identities require administrative resolution and do not receive access speculatively.
• Email changes update the directory identity without creating a second Kilo person or losing assignments.
• Identity merge/relink actions are explicit, authorized, and audited.
• A user that exists only in Kilo and has no matching directory identity is not modified by Directory Sync.

6. Desired-state and entitlement ownership semantics

• Effective directory-managed access is the union of all active mappings matching a user.
• Kilo tracks which source rule(s) justify each managed organization/group entitlement.
• Removing one source does not remove access while another active source still justifies it.
• Manual and directory sources may coexist for the same effective membership.
• Directory reconciliation may remove an effective assignment only when no active directory source and no manual source still justify it.
• A later manual grant converts/preserves the access as manual; subsequent directory removal must not remove that grant.
• Existing elevated sub-organization roles (owner, admin, or billing_manager) are never downgraded or removed by directory assignment reconciliation.
• Parent inherited access is not represented or counted as direct child membership.
• Concurrent mapping, manual-administration, login, and webhook activity converges to the same desired result without duplicate membership or lost manual changes.

7. Manual removal and suppression

Directory-desired access and an explicit Kilo-side removal can conflict. The behavior must be intentional:

• When an authorized administrator manually removes a directory-managed assignment, Kilo records a suppression for that user, destination, and directory authority.
• Repeated webhook delivery, reconciliation, or SSO login does not restore suppressed access.
• The administration surface shows the conflict and provides an explicit audited action to clear the suppression and restore directory management.
• Removing a user because the IdP deactivated them or removed the source assignment is not a permanent suppression. If the directory later grants the entitlement again, it can be restored.
• Suppressions are scoped to the relevant destination; removing one child/group does not suppress unrelated assignments.

8. Provisioning and deprovisioning behavior

For an active, linked directory user:

• Ensure parent membership when required by the directory configuration or a target prerequisite.
• Add missing child memberships as ordinary member memberships after all admission and capacity checks pass.
• Add organization-group memberships only after direct membership in the owning organization exists.
• Attribute all changes to the directory and mapping rule in audit history.

When a user stops matching a rule, is removed from a directory group, becomes inactive, or is deleted:

• Remove only managed entitlements that no remaining source justifies.
• Preserve manual grants and elevated roles.
• Invalidate cached/session-derived access to affected organizations promptly.
• Apply the same resource revocation and cleanup guarantees as an equivalent direct Kilo membership removal.
• Do not delete the person's global Kilo identity or unrelated organization/personal access.
• Do not revoke credentials globally when membership re-evaluation is sufficient, but credentials must not continue to authorize the removed organization.
• Report partial failures per user and destination and continue processing unrelated users.

If admission fails because of seats, policy, invalid hierarchy, suppression, or another business rule, the user remains unapplied/blocked for that destination. The system must not bypass the rule or report a successful sync.

9. Events, idempotency, and ordering

Consume the WorkOS Directory Sync events required to maintain directories, users, groups, and group membership, including user create/update/delete or activation changes and group membership changes.

• Verify every webhook using the WorkOS signature and raw request body.
• Reject invalid signatures without processing payload data.
• Acknowledge valid deliveries quickly and process them asynchronously.
• Store sufficient event identity/status to make duplicate delivery harmless.
• Handle events delivered out of order and prevent an older retry from overwriting newer object state.
• Upsert complete object state where available instead of assuming a prior create event arrived.
• Do not expose webhook secrets or identity payloads in logs, errors, analytics, or monitoring breadcrumbs.
• Retain a bounded operational record of event state and failure reason suitable for support and replay.

Relevant WorkOS behavior:

• Directory Sync overview
• Directory user attributes
• Directory Sync events
• Webhook delivery and ordering guidance
• Directory group API

10. Reconciliation and recovery

Webhooks are a change signal, not the only correctness mechanism.

• A full reconciliation can enumerate current directory users, groups, and memberships and compare them with Kilo's recorded desired/applied state.
• Reconciliation is safe to repeat and converges without generating duplicate memberships or unnecessary audit noise.
• Reconciliation runs periodically and can be triggered manually by an authorized administrator/support operator.
• Pagination and rate limits are handled for large directories.
• Interrupted runs resume or restart safely.
• Failed events can be retried after the underlying problem is corrected.
• The administration surface exposes last attempt, last success, counts of pending/blocked/failed records, and representative actionable errors.
• Mapping activation or material changes trigger reconciliation rather than requiring every source user to change in the IdP.

11. Administration and support experience

The organization administration surface provides:

• Directory connection/setup status and an entry point to the WorkOS Admin Portal.
• A mapping list showing source, target, status, match count, pending impact, last reconciliation, and errors.
• A mapping editor with searchable IdP groups/attributes and eligible Kilo targets.
• Preview and confirmation for activation, material edits, unmapping, and directory replacement/deletion.
• Per-user diagnostics showing directory identity, matched rules, desired assignments, applied assignments, manual sources, suppressions, and blockers.
• A safe “sync now” action.
• Explicit restore/clear-suppression controls.
• Clear distinction between directory-managed and manually managed memberships on relevant member/group views.

The UI must remain usable for large organizations: use server-side search/pagination and avoid requiring all directory users or all hierarchy memberships to be loaded in the browser.

12. Security, privacy, and auditing

• All setup, mapping, preview, synchronization, replay, relink, and suppression actions are authorized on the server.
• External WorkOS organization/directory IDs are validated against the local SSO authority before any membership mutation.
• Webhook signature verification uses a dedicated secret stored through the standard environment-secret workflow.
• Persist only identity attributes required for linking, configured matching, reconciliation, support, and audit obligations.
• Do not retain deprecated/raw IdP attributes as a general-purpose identity copy.
• User-data deletion/anonymization handles any new directory identity or attribute records.
• Audit records identify the organization, destination, affected user, action, directory, and rule without recording tokens, credentials, webhook secrets, authentication headers, cookies, or unnecessary raw attributes.
• Provisioning failures do not leak directory membership or attributes to unauthorized users.
• Directory disconnection and organization deletion have defined cleanup/retention behavior.

13. Scale and reliability

• The design supports directories with thousands of users and groups and bursty initial synchronization.
• Work is batched/queued so webhook response time and web-function duration do not constrain synchronization.
• Per-user/destination serialization or equivalent conflict control prevents races with login-time JIT and manual membership operations.
• Retries use bounded backoff and do not create audit/event storms.
• Metrics cover webhook validity, queue age, event/reconciliation lag, apply success/failure, blocked assignments, and drift repaired.
• Alerts distinguish infrastructure failure from expected per-user blockers such as seat exhaustion.

Delivery phases

All phases belong to this issue and must converge on the same data and ownership model.

Phase 1: Directory foundation and organization-group provisioning

• Directory setup/status through WorkOS.
• Signed webhook ingestion and asynchronous processing.
• Directory user/group identity storage and linking.
• Group/attribute mapping configuration, preview, and audit.
• Provenance-aware desired entitlement model.
• Provisioning into eligible Kilo organization groups.
• Initial and periodic reconciliation, diagnostics, and replay.

Phase 2: Sub-organization provisioning

• Explicit mapping to direct child organizations.
• Membership admission and seat/capacity enforcement.
• Ordinary-member-only creation and elevated-role protection.
• Suppression behavior for explicit manual removal.
• Resource cleanup and access invalidation on managed removal.
• Hierarchy-wide impact preview and administration.

Phase 3: Complete lifecycle and operations

• Pre-login/dormant user provisioning and robust first-login linking.
• Email change, deactivation, deletion, reactivation, and relinking behavior.
• Preservation of manual entitlements across all lifecycle changes.
• Full reconciliation at production scale, monitoring, alerts, support tooling, and operational runbooks.
• Staged customer rollout and recovery/rollback controls.

Rollout

• Gate the feature so it can be enabled for selected enterprise organizations first.
• Start with dry-run/preview mode and compare desired changes against current memberships before allowing mutation.
• Pilot organization-group targets before enabling child-organization removal behavior.
• Require an explicit administrator confirmation before the first authoritative sync for each mapping.
• Keep a kill switch that pauses new provisioning mutations without deleting currently applied access.
• Provide a documented recovery path that can reconcile from WorkOS after processing is resumed.

Acceptance criteria

• An authorized administrator can configure WorkOS Directory Sync and see connection/sync health.
• The administrator can map an immutable IdP group to a Kilo organization group and preview affected users.
• The administrator can map an allowed user attribute/value to a parent or direct child organization and preview affected users.
• Activating a rule provisions matching active users without requiring them to log in.
• A user not yet known to Kilo can be provisioned without receiving a non-SSO authentication path and is linked correctly on first SSO login.
• A group rename does not break or retarget a mapping; deletion is surfaced as an invalid source.
• A matching user receives only ordinary-member organization roles.
• Group membership is never created without explicit/direct membership in the group's organization.
• Multiple matching rules can justify one entitlement, and removing one rule preserves access justified by another.
• Manual grants survive IdP group removal, attribute changes, mapping deletion, and directory deactivation.
• Existing elevated child roles are never downgraded or removed by provisioning.
• Explicit manual removal creates a visible suppression and repeated sync/login does not restore the assignment.
• Clearing suppression restores an otherwise desired assignment and is audited.
• Directory-driven removal does not create permanent suppression; later reactivation can restore access.
• Deactivation/removal revokes only no-longer-justified managed access, invalidates affected access promptly, and performs required resource cleanup.
• Ambiguous identity matches are blocked and visible rather than guessed.
• Email changes do not duplicate the user or lose managed assignments.
• Duplicate, stale, and out-of-order webhook delivery converges to the correct state.
• Invalid webhook signatures cannot mutate state.
• Full reconciliation repairs a deliberately missed event and is safe to run repeatedly.
• Mapping edits/deletion show additions and removals before confirmation and preserve shared/manual access.
• Seat/capacity or policy failures are reported per user/destination and are not reported as successful provisioning.
• Audit records distinguish directory-managed changes, manual changes, suppression, restoration, and administrative overrides.
• Logs and monitoring do not contain tokens, credentials, webhook secrets, auth headers/cookies, or unnecessary raw identity attributes.
• New stored identity data participates in user deletion/anonymization behavior.
• Large-directory processing is paginated/batched, asynchronous, retryable, and observable.
• Automated tests cover mapping evaluation, identity linking, provenance union, suppression, elevated-role protection, deactivation/reactivation, webhook verification/idempotency/ordering, reconciliation, authorization, and cleanup failures.

Test scenarios

At minimum, automated integration coverage should include:

1. New active directory user matching one group rule.
2. Existing SSO user linked to a directory record.
3. User matching multiple rules for the same target.
4. User matching parent, multiple child, and organization-group targets.
5. Group target whose direct-membership prerequisite is missing or blocked.
6. Group rename and deletion.
7. Attribute change from one target value to another.
8. Missing, null, malformed, scalar, and multi-valued attributes.
9. User email change without identity duplication.
10. Ambiguous email/identity collision.
11. User deactivation, deletion, and later reactivation.
12. Manual grant coexisting with a managed grant.
13. Manual removal/suppression and explicit restoration.
14. Existing child owner, admin, or billing_manager encountering a removal event.
15. Seat or admission failure in one child while another target succeeds.
16. Removal requiring downstream resource cleanup, including cleanup failure/retry.
17. Duplicate event delivery.
18. Membership event arriving before user/group creation.
19. Older event arriving after newer object state.
20. Missed event repaired by full reconciliation.
21. Mapping pause, reactivation, edit, and deletion.
22. Directory replacement/deletion with previewed managed-access impact.
23. Unauthorized configuration, replay, relink, and suppression requests.
24. Invalid/missing WorkOS signature.
25. Initial synchronization of a large paginated directory.

Definition of done

The feature is complete when all three phases are production-capable for selected enterprise customers, directory and Kilo state converge without login-time dependence, deprovisioning cannot remove unrelated manual/elevated access, operators can detect and repair drift, and administrators can understand the impact and source of every managed assignment.