Manage users and organization memberships via directory sync providers.
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 IT admins full control over user and membership management, eliminating the need for manually adding or removing members. Users from a directory are pre-provisioned and managed by their Identity Provider.
A Directory Sync integration will need to be configured for every organization that wants to source users and 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.
Directory provisioning is supported for all SCIM directory providers, Google Workspace, and SFTP.
Users provisioned through a directory with an email domain matching a verified organization domain will be automatically added as members of the organization, without needing an invitation.
Other users are created with pending memberships and receive an email invitation to join the organization. Pending members cannot sign in until the invitation is accepted, at which point they become active organization members.
Invitation emails can be disabled if you prefer to manage invitations with a custom approach.
In addition to provisioning new users, any updates to existing users and de-provisioning events will be reflected in AuthKit.
Users with email addresses matching one of the organization’s verified domains are fully managed by the directory. Updates to their attributes from the directory will override changes made through SSO, the API, or manually in the dashboard.
If multiple organizations with directory provisioning contain the same verified domain, the user’s name will always reflect the most recent directory update.
Other users, with email domains not verified by the organization, will not be fully managed by the directory, so updates made via SSO, API, or manually in the dashboard will persist.
When a user is de-provisioned in the directory, the status of their corresponding organization membership will be set to inactive. While the user will no longer be able to sign in to the organization, the membership and user are not automatically deleted.
If a user is re-provisioned in the directory, their organization membership will be reactivated with its previous role and its status will be set to active.
When using directory provisioning, custom attributes configured on directory users are available on the corresponding organization membership. This allows you to access IdP-sourced attributes like department, job title, and cost center directly from the membership object or in JWT templates.
When a directory user’s attributes are updated, the changes are automatically reflected on the linked organization membership’s custom_attributes.
If the membership is also linked to an SSO Profile, the directory user’s custom attributes take precedence.
Below is a list of directory provisioning and deprovisioning actions and the corresponding changes triggered in AuthKit. If you’re using standalone Directory Sync, refer to the standalone Directory Sync documentation.
Actions depend on the user’s email domain:
| Directory Action | Changes triggered in WorkOS | Event(s) Emitted |
|---|---|---|
| Directory user provisioned | User and organization membership objects created. Domain-managed users are created with an active status, while domain guest users are invited to the organization with a pending status. | user.created, organization_membership.created |
| Directory user info updated | For domain-managed users, any updates to the user’s name will be reflected on the user object. Otherwise, the user object will not be modified. User email address is always immutable. | user.updated, organization_membership.updated |
| Directory user with active membership deprovisioned | Organization membership deactivated and all sessions for the user are revoked. Their role is reset to the default role. | organization_membership.updated |
| Directory user with pending membership deprovisioned | Organization membership deleted. | organization_membership.deleted |
| Directory user reactivated | Organization membership reactivated. | organization_membership.updated |
Directory users need to have a primary email address to be provisioned in AuthKit. 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 AuthKit, as emails are unique to AuthKit users.
The email address on the User object is immutable, but the email on the underlying directory user object will be modified.
For domain-managed users, the organization has proven they own the email domain through domain verification, and therefore have full control over the user’s account and email. This allows the directory to manage all aspects of the user object.
For domain guests, the organization has not proven ownership of the user’s email domain. As a result, the organization only has the ability to manage data within the scope of the organization itself, represented by the organization membership object.
User deprovisioning and directory deletion have different behaviors because they serve different use cases. Deactivating all users is typically an off-boarding task that affects the entire organization, not just the directory. By leaving memberships active when a directory is deleted, customers can switch directory providers without the disruption of deactivating all memberships.