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 their own 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.
Organization admins can assign roles to identity provider groups in the Admin Portal during SSO or directory setup.
From the Roles and Permissions section in the WorkOS Dashboard, role assignment is an environment-level setting. However, it can also be configured per organization via the Roles tab on that organization’s page. If enabled, all Admin Portal sessions for the relevant SSO connection or directory will support group role assignment.
Whether to enable role assignment for SSO or directory groups depends on your application’s setup. When provisioning users with Directory Sync, we recommend enabling directory group role assignment due to limitations of SSO role assignment.
If you’re not yet using directory provisioning, you can enable SSO group role assignment as the environment default.
Because this setting is configurable per organization, choose a sensible default based on your customers’ typical setup:
-
A. All organizations use SSO:
If no organizations are using Directory Sync, enable SSO group role assignment in Admin Portal at the environment level. -
B. Some organizations use Directory Sync:
Enable directory group role assignment in Admin Portal for those specific organizations. -
C. Most organizations use Directory Sync:
Enable directory group role assignment in Admin Portal at the environment level, and override the setting for organizations that only use SSO.
When switching from one role assignment source to another, refer to the section below.
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 user organization membership’s role for that session.
You can map identity provider groups to roles to automatically assign roles to users. AuthKit supports two methods for role assignment:
Roles can be assigned via SCIM through directory group role assignment. Admins can map group memberships to roles in the Admin Portal during SCIM or Google Workspace directory setup. These mappings are used to assign roles to organization memberships via Directory Provisioning.
Roles can also be assigned via SSO 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 belongs to a mapped group, the corresponding role will be set on the organization membership and reflected in the user’s session.
Ensure SSO JIT provisioning is enabled for each organization using SSO role assignment.
It’s recommended to use only one role assignment source per organization. If your organization currently uses SSO group role assignment and you’d like to switch to directory group role assignment, consider the following paths:
-
A. Directory is not yet configured:
Enable directory group role assignment for this organization via the Roles tab under an organization in the WorkOS Dashboard. The organization admin will be prompted to set up directory group role assignments in the Admin Portal. -
B. Directory is already configured:
Manually assign roles to directory groups in the WorkOS Dashboard, or regenerate an Admin Portal link so the organization admin can set the role mappings there.
Directory group role assignments take precedence and will override any SSO group role assignments on the organization membership. Once directory group roles are properly set up and reflected, you can delete the SSO group mappings.
Organization roles are custom roles scoped to a particular organization. They are managed via the “Roles” tab under an organization in the WorkOS Dashboard.
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.
