Roles and Permissions
Manage and assign roles and permissions to users.
A role represents a logical grouping of permissions, defining access control levels for users within your application. Roles are identified by unique, immutable slugs and are assigned to users through organization memberships.
Permissions grant users privileged access to resources and actions in your application and are referenced in your code by unique, immutable slugs. A permission can be assigned to any number of roles.
Roles alone can be sufficient when your application only requires very coarse-grained access control. This is suitable if users only need to be separated into broad categories and there is minimal overlap between roles. Simple roles can be easier to manage, but are less flexible for complex access control scenarios.
Permissions allow for more detailed and flexible management of access. They are particularly useful when:
- You anticipate the need to frequently modify access rights or introduce new roles.
- There is significant overlap in access rights between different roles, but with some variations.
- You want to minimize code changes when modifying access rights. By abstracting access control checks to permissions, you can add or modify roles and their access rights without changing the application code.
Roles and permissions are managed in the Roles section of the WorkOS Dashboard.
When configuring permissions, we recommend:
- Defining a common naming scheme to use across all permissions for your application. Consider separating the resource and action with a delimiter, such as
users:view. The following delimiters are permitted:-.:_. - Keep permission slugs clear and concise. When assigned to roles, these slugs will included as part of session cookies in the session JWT claims, which is limited to a maximum size of 4KB in many modern web browsers.
Permissions can be assigned when creating a new role or when editing an existing role.
Role configuration occurs at the environment level. Each environment is seeded with a default member role, which is automatically assigned to every organization member. This default role cannot be deleted, but any role can be set as the default.
If you need to set default roles or other role configurations at the organization level, refer to the Organization roles section.
Organization memberships require a role. Every user with an organization membership is automatically assigned the default role when added to an organization. This role can be edited.
You can retrieve the role slug from the user’s organization membership object to determine their access level and capabilities within your application.
When roles are deleted, all organization memberships are reassigned to the default role. Role deletion happens asynchronously, so there may be a slight delay between deleting a role and updating all organization memberships.
To migrate from one default role to another, set the new default role and delete the old one. All users will then be reassigned to the new default role.
If a user is provisioned from multiple sources with conflicting roles, the role with the highest priority will be assigned.
When provisioning users with Directory Sync, allow IT admins to assign roles to groups during directory setup in Admin Portal. This is an environment-level setting. If enabled, all Admin Portal sessions for SCIM-based or Google Workspace directories will have the ability to assign roles to groups.
When a user signs into your app, a user session is initiated. The authentication response includes an access token, a JSON Web Token (JWT), with the “role” claim indicating the organization membership’s role for that session.
Map identity provider groups to roles to automatically assign roles to users. There are two supported methods for role assignment in AuthKit:
Roles can be assigned via SCIM through directory group role assignment. Admins can map group membership to roles in the Admin Portal during SCIM and Google Workspace directory setup. These mappings can then be used to set the role on the organization membership via Directory Provisioning.
Roles can also be assigned from the identity provider via SSO through connection group role assignment. Groups returned in the SSO profile can be mapped to roles in the WorkOS Dashboard. If an AuthKit user authenticates via SSO and they are a member of a group with a role assignment, that role will be set on the organization membership and be reflected in the user’s session.
If your organization has a directory connection configured, it is recommended to use the directory for role assignment. Contact support if you need to migrate from SSO role assignment to directory role assignment.
Organization roles are custom roles scoped to a particular organization. They are managed via the “Roles” tab under an organization in the WorkOS Dashboard.
Organization roles are in feature preview. Reach out to WorkOS support to gain access.
Why might I use organization roles?
In some cases, an application’s fixed set of roles may not meet the needs of certain organizations. For example, an organization may require a lesser privileged set of permissions for their members. Organization roles allow you to create custom roles, with the organization’s desired set of permissions, without affecting access control for other organizations.
By default, organizations have no custom organization roles and simply inherit the environment-level roles. You can create an organization role by clicking the “Create role” button on the organization’s “Roles” tab. All organization role slugs are automatically prefixed with org.
Once you create the first role for an organization, that organization will have its own default role and priority order, independent from the environment.
New roles added to the environment will be available to the organization and placed at the bottom of the organization’s role priority order.
Like environment-level roles, organization roles can be used in role assignment, sessions, and the organization membership API. No additional action is required to enable this behavior after creating organization roles.
When attempting to delete an environment role that’s the default role for one or more organizations, you’ll be prompted to select a new default role for all affected organizations. Organization members previously assigned the deleted role will be assigned the new organization default role.
