Learn about common app architectures and edge cases for mapping roles.
Apps take different approaches to allow customers to map groups and attributes from their directory providers to roles in the app. For example, some apps chose to surface UI to their end users to perform the mappings. Other times, apps perform the mappings opaquely.
This guide will go over common strategies to allow your customers to map roles in your app.
If your app does not support roles, you can essentially ignore the group or attribute-based role data provided by WorkOS. You can build an additional role system at a later date. You can always pull directory group information and perform a migration in your app – to backfill any role data.
Maintaining a fixed set of roles is the most common approach apps take. B2B apps often surface a concise set of roles to their users, such as an “Admin”, “Editor”, and “Viewer” role.
A common approach to creating the role mappings is to build a surface in your app that shows an admin the groups associated with their directory provider. Then, your customer can map these groups to roles in your app. Your app then stores the mapping between directory group IDs and roles. Group assignment is the preferred app assignment workflow for many IT admins as it saves on manual per-user assignments.
As an alternative to building UI, some apps choose to store mappings in a configuration file i.e. a JSON or YAML file.
Alternatively, a custom-mapped attribute can be used as a direct mapping if you cannot support UI. Your app will receive all custom attribute changes in real-time.
When your customer first activates their directory, your app will not have role mapping configuration set at this point. Despite this, WorkOS will send you events based on changes to the directory. To account for the role mapping not being set, you can grant all incoming users a default role until the role mapping setup is complete.
After that point, you can backfill existing users with the correct roles. To backfill, you can initiate a sync to pull the latest directory state using one of the WorkOS SDKs.
Often, custom role creation functionality uses RBAC under the hood. For example, you can use RBAC alongside Directory Sync to map custom role information to your customer’s custom roles. This workflow remains the same as the fixed roles architecture, with an additional role creation UI in your app. Creating mappings is performed as usual, with IT admins additionally allowed to create custom roles.
You can use a custom-mapped attribute as a direct mapping in this scenario. First, you’ll have to let your customers know the new role value allowed in their directory provider. Then, the IT admin must ensure they pass the correct newly created role via their directory provider.
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. The most common way to map multiple groups to a role is to grant the user the role associated with the most privileged group. In this case, “Admin” has the most permissions, giving Jane the “Admin” role.
Another common approach is to add the permission sets together to grant the user all permissions associated with each role assigned to each group. This role addition means the user receives every permission for each role.
Your customer might want to retain the ability to override a role for a particular user. WorkOS recommends achieving this by using both a group and attribute-based approach. Roles map to groups by default but can be manually modified with attributes if the attribute exists in the directory provider.
You can also build override functionality by flagging a specific user’s role as having been set by either Directory Sync or an IT admin. For this case, your app should not sync this particular user’s role from now on, nor have new directory group events overwrite their manually inputted role.