Integrating Role-Based Access Control

Configure roles and permissions for your application in the WorkOS Dashboard before integrating with WorkOS Role-Based Access Control (RBAC).

Integrate WorkOS RBAC with AuthKit to assign roles directly to organization memberships, source roles from your customer’s identity provider (IdP), and read roles and permissions directly from session JWTs.

Assign roles to users through organization memberships. Each organization membership has role(s) representing a user’s access level for that particular organization. Every organization membership is automatically assigned the default role when added to an organization.

Modify an organization membership’s role(s) via the organization memberships API, WorkOS Dashboard, or via IdP role assignment.

Note that IdP role assignment always takes 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 a directory event is received for the user.

AuthKit, Directory Sync, and Single Sign-On all support both single and multiple role paradigms. Assign multiple roles in two ways:

• Group-based assignment: When a user belongs to multiple groups with role mappings, they receive all mapped roles. This applies to directory users, SSO profiles, and organization memberships when using directory or SSO JIT provisioning in AuthKit.
• Manual assignment: Assign multiple roles to organization memberships directly via the WorkOS Dashboard or API.

Use multiple roles to avoid 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.

Start with single-role assignments 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. Use these values to control access to resources in your application.

For standalone Directory Sync, manage roles through directory group role assignment. The assigned role defines the user’s access level for the particular organization 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 group membership updates are received.

Use the role slugs returned on Directory User objects from the API to assign a role to your internal user object.

For standalone SSO, manage roles via SSO group role assignment. The 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.

Use the role slugs returned on SSO Profile objects from the API to assign a role to your internal user object based on group memberships.