Learn how to map role data from identity providers to roles in your app.
A role represents a logical grouping of permissions, defining access control levels for users within your application. Roles are identified by a unique, immutable slug and are assigned to Directory Sync users through their group memberships. These role assignments can be configured on the WorkOS dashboard.
Role configuration occurs at the environment level. Each environment is seeded with a default member
role, which is automatically assigned to every directory user. 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, please contact us.
If a user is provisioned from multiple groups with conflicting roles, the role with the highest priority will be assigned.
When a role is deleted, all users with that role, will be granted the default role. Role deletion happens asynchronously, so there may be a slight delay between deleting a role and updating all directory users.
To migrate from one default role to another, set the new default role and delete the old one. All directory users will then be reassigned to the new default role.
Users are assigned to groups via the identity provider. Groups are typically synonymous with roles in your app. Therefore, IT admins will often map a group one-to-one to a role. This can be defined within the WorkOS dashboard or Admin Portal for your application to receive automatic role updates.
Only supported in directories using SCIM-based or Google Workspace providers.
Consider the fictional SaaS company HireOS. HireOS has integrated Directory Sync and supports group-based role assignment. For example, a HireOS customer would like to assign their engineering team to it. The customer’s IT admin would take the following steps:
The developer on the WorkOS dashboard can then assign users of that group to the role “Viewer”.
From this point on, all new users added to “Engineering will be given “Developer” role from the WorkOS API. The role will be in the directory user response.
Once roles for your application are configured, enable role assignment in Admin Portal to allow IT admins to assign roles to groups during directory setup. This is an environment-level setting. If enabled, all Admin Portal sessions for SCIM-based or Google Workspace directories will have the ability to see and assign roles to groups.
Your customers will store role information in different forms, depending on their preferred provisioning workflow. WorkOS allows for flexibility in how you source role data, though these formats are not automated today and not available on the role property on the directory user response. You can fetch role data via two distinct mechanisms:
The type of mechanism needed will depend on the level of support for roles in your app, your app’s architecture, and your customer’s workflows:
Approach | Your app | Your customer |
---|---|---|
Attribute mapping | Sets roles based on a per-user custom-mapped attribute | Assigns roles using attributes on individual users in their identity provider |
SSO attribute mapping | You get role data each time a user logs in (JIT user provisioning) | Uses groups in their identity provider to assign roles in your app |
This feature is currently in beta, contact customer support for more information.
If you have integrated WorkOS Single Sign-On, you can retrieve groups via the groups
attribute in an SSO user profile. There are drawbacks to using SSO-based groups compared to the directory group approach, but it can be quick to set up in some cases.
{ "object": "profile", "id": "prof_01DMC79VCBZ0NY2099737PSVF1", "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5", "connection_type": "OktaSAML", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "email": "todd@example.com", "first_name": "Todd", "last_name": "Rundgren", "idp_id": "00u1a0ufowBJlzPlk357", "groups": ["Admins", "Developers", "Engineering"], "raw_attributes": {} }
You can use these group name(s) to map onto user roles in your app using JIT user provisioning.
Strictly using JIT user provisioning comes with a few caveats:
groups
attribute in the SSO setup so that you can retrieve that attribute in the SSO profile.For more information, see the JIT user provisioning guide.
You can use custom-mapped attributes if your customers do not use groups to establish and manage user roles.
You can create a custom-mapped attribute role (e.g., myRole
) in the WorkOS Dashboard under Configuration → Directory Sync. You can set the status of a role attribute to “Required” or “Optional”.
{ "id": "directory_user_01E1X7B89OH8Z3SXFJR4H7RGX7", "idp_id": "821991", "first_name": "Jane", "last_name": "Doe", "job_title": "Engineering Manager", "username": "jane@example.com", "emails": [ { "type": "work", "value": "jane@example.com", "primary": true } ], "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "object": "directory_user", "directory_id": "directory_01E1X194NTJ3PXMAY79DYV0F0P", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3PJNY", "custom_attributes": { "myRole": "admin" }, "raw_attributes": {} }
The newly created attribute will appear as a field in the Admin Portal. When setting up Directory Sync with their identity provider in Admin Portal, your customers can map this role field to a field in their identity provider. You’ll have to communicate with your customer what value(s) you expect in the custom-mapped attribute.
An example being that myRole
should be one of "admin"
, "viewer"
, or "editor"
. This allows your app to parse the myRole
field value correctly.
Having a user who belongs to multiple groups is a common scenario. For example, there might be a case where an employee Jane is an Engineering Manager and belongs to an “Engineering”, “Manager”, and “Admin” group. With group-based role assignment, the user will be assigned the role that has the highest priority defined.