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, users are associated with organizations via organization memberships. Each organization membership has role(s), 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(s) 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.

WorkOS AuthKit supports both single and multiple role paradigms.

Multiple roles lets you assign more than one role to an organization membership. A user receives the union of permissions across those roles. This helps to avoid “role explosion” or creating roles for every possible combination of permissions e.g., designer-engineer. This model fits teams where users span functions or need additive, temporary access.

For most apps, start with single-role memberships for simplicity and predictability, and adopt multiple roles only when overlapping permission sets become common.

Read a user’s role(s) from their organization membership or from 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.