Integrating Role-Based Access Control

Before integrating with WorkOS Role-Based Access Control (RBAC), you’ll need to configure roles and permissions for your application in the WorkOS Dashboard.

WorkOS RBAC seamlessly integrates with AuthKit to provide a complete user management solution. Using AuthKit, you can assign roles directly to organization memberships, source roles from your customer’s identity provider (IdP), and read roles and permissions directly from session JWTs.

In AuthKit, user’s are associated with organizations via organization memberships. Each organization membership has a role, which represents a user’s access level for that particular organization. Every organization membership is automatically assigned the default role when added to an organization.

You can modify an organization membership’s role via the organization memberships API, WorkOS Dashboard, or via IdP role assignment.

IdP role assignment will always take precedence over roles assigned via API or the WorkOS Dashboard. For SSO group role assignment, the organization membership role updates each time the user authenticates. For directory group role assignment via directory provisioning, the organization membership’s role updates each time we receive a directory event for the user.

To determine a user’s access level and capabilities within your application for a particular organization, you can retrieve the role slug from the user’s organization membership object, or via an AuthKit session access token.

For standalone Directory Sync, organization administrators manage roles through directory group role assignment. Their assigned role defines the user’s access level for the particular organization and is based on their directory group memberships.

All directory users have assigned roles. If no role is explicitly assigned through directory group role assignment, the user receives the default role. Roles are granted to directory users in real-time, when we receive updates to their group memberships.

Role slugs are returned on Directory User objects from the API. These can be used to assign a role to your internal user object.

For standalone SSO, organization administrators manage roles via SSO group role assignment. Their assigned role defines the user’s access level for the particular organization.

All SSO profiles have assigned roles. If no role is explicitly assigned through SSO group role assignment, the user receives the default role. Roles are granted to SSO profiles when the user authenticates.

Role slugs are returned on SSO Profile objects from the API. These can be used to assign a role to your internal user object based on group memberships.