Learn how to map role data from directory providers to roles in your app.
User roles designate what actions a user can perform in your app and what resources they can access. Directory providers store information about user roles in the form of groups or attributes.
This guide will explain common strategies for sourcing roles from directory providers and mapping them to roles in your app.
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. You can fetch role data via three 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 |
---|---|---|
Group mapping | Sets roles based on your customer’s directory groups | Uses groups in their directory provider to assign roles in your app |
Attribute mapping | Sets roles based on a per-user custom-mapped attribute | Assigns roles using attributes on individual users in their directory provider |
SSO attribute mapping | You get role data each time a user logs in (JIT user provisioning) | Uses groups in their directory provider to assign roles in your app |
Users are assigned to groups via the directory provider. Groups are typically synonymous with roles in your app. Therefore, IT admins will often map a group one-to-one to a role.
Consider the fictional SaaS company HireOS, which offers recruiting software to other businesses. HireOS is an online application allowing customers to track leads, candidates, and interviews.
HireOS has integrated Directory Sync and supports group-based role mapping. For example, a HireOS customer would like to assign their recruiting team to it. The customer’s IT admin would take the following steps:
From this point on, all new users added to “Recruiting - HireOS Viewer” will be given “viewer” permissions on HireOS.
There are two ways to access group data. You can source group data from directory group objects or the SSO-based groups attribute if your app is using WorkOS Single Sign-On.
WorkOS normalizes group information across directory providers, so the information you receive is consistent. Your app only interfaces with a directory group.
{ "id": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z", "idp_id": "02grqrue4294w24", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "name": "Developers", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "raw_attributes": {} }
Your app stores the mapping between the directory group ID and the directory user ID. This relationship defines group memberships for any given user. Keeping an additional mapping between the directory group ID and a role in your app allows you to determine which role a user receives.
Directory groups are a powerful tool to provision users with the correct roles inside your app. WorkOS automatically sends changes to a given directory group to your app. As a result, your app is always up-to-date with real-time updates when an IT admin changes a user’s access to resources. This way, you ensure only authorized users get access to resources without delay.
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@foo-corp.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": "[email protected]", "emails": [ { "type": "work", "value": "[email protected]", "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 directory provider in Admin Portal, your customers can map this role field to a field in their directory 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.