Role Data

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.

Role

A primitive in your app that defines specific permissions for the users. Roles are often defined as an ability or a job title, for example, “Editor” or “Accountant”.

Group

A collection of users based on shared traits. Groups are defined and managed by IT admins in the directory provider.

JIT user provisioning

Just-in-time (JIT) user provisioning creates a user in an app when the user attempts to sign in for the first time. The account and respective role doesn’t exist until the user creates it – just-in-time.

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:

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.

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:

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.