Identity Provider Role Assignment

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.

You can manage roles in the Roles section of 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, refer to the organization roles documentation.

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.

Users are assigned to groups via the identity provider. Groups usually correspond to 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.

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 “Developer”.

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:

Connection group-based role assignment involves mapping identity provider (IdP) groups to roles within your application during Single Sign-On and JIT Provisioning. In this method, connection groups corresponding to IdP groups are defined in the WorkOS Dashboard, and roles are assigned based on these group memberships.

The user’s role is then included in the SSO profile returned from WorkOS. Read more on this approach, including drawbacks to consider.

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.

Identity provider role assignment through groups is only available through SCIM compliant and Google Workspace directories.