Identity Provider Role Assignment

Learn how to map role data from identity providers to roles in your app with SSO.

Introduction

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.

Configure roles

You can manage roles in the Roles section of the WorkOS Dashboard.

Default role

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, please contact us.

Priority order

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.

Delete roles

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

To migrate from one default role to another, set the new default role and delete the old one. SSO user profiles will then receive the new default role at the next sign-in.

Connection group role assignment

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.

Supported in both SAML and OIDC-based connection types, except for Okta OIDC. Reach out to us if you need this for an Okta OIDC connection.

Sample scenario

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:

Create an “Engineering” group using their identity provider.

Configure the groups attribute in their SAML app to return the group memberships.

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

Navigate to the Connection section of the WorkOS dashboard.

Create a connection group defining the IdP ID for the “Engineering” group, assign the to the “Developer” role.

Dialog to create connection group with role assignment

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.

SSO user profile

JSON

 {
  "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": {}
}

When a user is not a member of any groups or their groups do not match with connection group role assignments, the user will be granted the default role in the SSO profile.

Considerations

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.

Drawbacks

Strictly assigning roles during JIT user provisioning and 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.

Connection groups need to be manually defined. You need to communicate with your customer to retrieve the exact IdP IDs for the groups to create functioning role assignments.

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 group role assignment

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.