IdP Role Assignment

Identity Provider (IdP) role assignment is the process of mapping identity provider groups to roles to automatically assign roles to users.

Users are assigned to groups via the identity provider. Groups usually correspond to roles in your app. Therefore, IT admins will often map a group one-to-one to a role. This can be defined within the WorkOS dashboard or Admin Portal for your application to receive automatic role updates.

Roles can be assigned from the identity provider via Directory Sync through directory group role assignment. Admins can map groups to roles in the Admin Portal during SCIM and Google Workspace directory setup. You can also manage these assignments in the WorkOS Dashboard.

Enterprise organizations typically use SSO to manage user authentication and SCIM (Directory Sync) for user lifecycle management. While access management can be automated through either SSO or SCIM, SCIM is generally the preferred option due to its real-time synchronization capabilities.

Roles can be assigned from the identity provider via SSO through SSO group role assignment. Admins can map groups to roles in the Admin Portal during SSO connection setup. You can also manage these assignments in the WorkOS Dashboard.

A key limitation of SSO-based role assignment is that changes made in the identity provider (IdP) only take effect after the user re-authenticates. In contrast, SCIM propagates changes immediately without requiring user interaction, enabling applications to revoke sessions and enforce access updates in real time.

If you are integrating with AuthKit, our full user management solution, roles are automatically assigned to the appropriate organization membership. These roles are also reflected in the user’s session token, ensuring consistent access control across your application.

When using SSO group role assignment, roles are populated on the organization membership through SSO groups, allowing role assignment based on your customer’s identity provider configuration each time a user authenticates.

When using Directory Sync group role assignment, roles are populated on the organization membership through directory provisioning, allowing for seamless, real-time role assignment based on your customer’s identity provider configuration.

If a user is provisioned from multiple groups with conflicting roles, the role with the highest priority will be assigned.

Explicit role assignments are created by manually mapping an IdP group to a role in the WorkOS Admin Portal or Dashboard.

Default role assignments are created for any IdP group that does not have an explicit role mapping. Default group role assignments are always mapped to the configured default role.

You can choose to show or hide the role assignment step in Admin Portal, and whether to show the steps for Directory Sync or SSO at an environment level on the Roles & Permissions page in the WorkOS Dashboard.

For your customers that may have a different setup, you can override the role assignment in Admin Portal setting per-organization, on the Roles tab of the organization page in the WorkOS Dashboard. For example, if most customers use Directory Sync but a few only use SSO, select “Directory groups” role assignment at the environment level, and select “Single Sign-On groups” at the organization level for the exceptions.