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 & Permissions 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 SSO 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:

1. Create an “Engineering” group using their identity provider.
2. Configure the groups attribute in their SAML app to return the group memberships.
3. Provide the developer with the IdP ID for the “Engineering” group.

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

1. Navigate to the Connection section of the WorkOS dashboard.

2. Create an SSO group defining the IdP ID for the “Engineering” group. Then, assign this group to the “Developer” role.

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": "[email protected]",
  "first_name": "Todd",
  "last_name": "Rundgren",
  "idp_id": "00u1a0ufowBJlzPlk357",
  "role": {
    "slug": "developer"
  },
  "raw_attributes": {}
}

Once roles are configured for your application, enable SSO group role assignment in Admin Portal to allow IT admins to assign roles to groups during SSO connection setup. If enabled, all Admin Portal sessions for SSO connections will have the ability to configure and assign roles to groups.

This is an environment-level setting, but can be configured per organization via the Roles tab under an organization in the WorkOS Dashboard.

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 has a few caveats:

• Your customer must explicitly map the SAML groups attribute in the SSO setup so that you can retrieve that attribute in the SSO profile.
• SSO groups need to be manually defined.
• Your app will receive updates to this user’s group data only once they sign-in with SSO again. This delay can allow unauthorized users to access resources using a stale role.

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’s recommended to use only one method of role assignment – either from a Directory or an SSO Connection – to avoid overlap.