Manage users and organization memberships via directory sync providers.
This feature is currently in preview. Please reach out to support@workos.com or via your team’s WorkOS Slack channel if you would like Directory Provisioning enabled.
Directory provisioning gives an IT admin full control over access to an organization’s resources, without relying on manual entry. Users from a directory are pre-provisioned and managed by their Identity Provider.
A Directory Sync integration will need to be configured for every domain, i.e. organization, that wants to source users and organization memberships via directory provisioning. Directories can be set up via the WorkOS Dashboard with Setup Links. You can also integrate the Admin Portal with your app to generate links to configure directories.
The following directory sync providers are supported with directory provisioning:
If you are interested in directory provisioning support from a directory sync provider not listed above, please reach out to support@workos.com or via your team’s WorkOS Slack channel.
When directory provisioning is enabled and a directory sync provider integration is set up, domain-captured users from the directory sync provider will be provisioned for the organization.
Users with email addresses that match the organization’s verified domain are immediately added as active
members to the organization. All other users become pending
and are sent an email invitation. The invitation must be accepted for the user to become an active
organization member.
You can disable invitation emails if you prefer to manage user invitations yourself.
Once directory provisioning is set up for an organization, any additional users, updates to current users, and de-provisioning events will flow through to User Management.
Domain-captured users will be fully managed by the directory, and updates to attributes will supersede updates from SSO, the API or manually in the dashboard.
Users with email addresses that do not match the organization’s domain will not be fully managed by the directory, and SSO, API or manual updates in the dashboard will persist.
When a user is de-provisioned in the directory, the corresponding organization membership will become inactive and the status for the membership will be inactive
. De-provisioning will not automatically delete users or organization memberships.
If a user is re-provisioned in the directory, the corresponding organization membership will be reactivated and the status for the membership will be active
. The organization membership’s pre-existing role will be retained.
Below is a list of directory provisioning and deprovisioning actions and the corresponding changes triggered in WorkOS User Management. If you’re using standalone Directory Sync, refer to the standalone Directory Sync documentation.
Directory Action | Changes triggered in WorkOS | Event(s) Emitted |
---|---|---|
Directory user provisioned | User and organization membership objects created. | user.created, organization_membership.created |
Directory user info updated | If the user is domain-managed, any updates to the user’s name will be reflected on the user object. If the user is a domain guest, the user object will not be modified. User email address is always immutable. | user.updated |
Directory user deprovisioned | Organization membership deactivated and all sessions for the user revoked. Their role is reset to the default role. | organization_membership.updated |
Directory user reactivated | Organization membership reactivated. | organization_membership.updated |
Directory users need to have a primary email address to be provisioned in User Management. If the directory user is missing a primary email, they won’t be provisioned. Additionally, if the primary email of a directory user is shared by another directory user, only one will be provisioned in User Management, as emails are unique to User Management users.
The email address on the User object is immutable, but the email on the underlying directory user object will be modified.