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 SSO user profiles through their identity provider group memberships. These group role mappings 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 new profile. The 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.

Role priority order determines which role is assigned when a user sign-ins with multiple groups that contain conflicting role mappings. In that scenario, the role with the highest priority will be assigned. 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.

When a role is deleted, all SSO user profiles with that role will be granted the default role.

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.

During authentication, a user’s identity provider group memberships can be read via attributes. This enables you to define connection groups that correspond to IdP groups and set role assignments for those groups in the WorkOS Dashboard.

Based on these settings, SSO user profiles returned from WorkOS will include a role attribute that reflects their highest priority group membership. The SSO user profile role is calculated during each sign-in.

Consider the fictional SaaS company HireOS. HireOS has set up an SSO Connection and configured group-based role assignment. For example, a HireOS customer would like to assign their engineering team to the application. The customer’s IT admin would take the following steps:

In the WorkOS dashboard, the developer can then assign users of that group to the role “Developer”.

From this point on, whenever a user in the “Engineering” group authenticates via SSO, they will be granted the “Developer” role for that session from the WorkOS API. The role will be returned in the profile response.

{
  "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",
  "role": {
    "slug": "developer"
  },
  "raw_attributes": {}
}

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. However, there are some considerations to keep in mind when using SSO-based connection groups for role assignment.

Strictly assigning roles during JIT user provisioning and has a few caveats:

Directory Sync supports group-based role assignment and avoids the pitfalls mentioned above. For organizations with a directory, this method of group-based role assignment is preferred.

It is recommended to only use one method of role assignment, either from a Directory or a Connection, to avoid overlap.