How to map role data from identity providers to roles in your app

A role represents a logical grouping of permissions, defining access control levels for users within your application. You define the roles first, and then you assign them to users.

Nowadays, when employees use several different apps to do their work, configuring roles in each app is not an option. Instead, the common practice is to configure the roles in the identity provider (IdP) and send them automatically to other apps. This is what we call role assignment.

WorkOS supports role data mapping using SSO or SCIM. In this article, we will review both options and see how you can implement them with WorkOS.Configure rolesFirst, you must add your app’s roles in the Roles section of the WorkOS dashboard.

Configure roles

First, you must add your app’s roles in the Roles section of the WorkOS dashboard.

For each role, set the following information:

• Name: a user-friendly name of the role.
• Slug: a unique and immutable case-sensitive key that you will use to reference the role in your code.
• Description (optional): a user-friendly description of the role.
• Permissions: they grant users privileged access to resources and actions in your application and are referenced in your code by unique, immutable slugs (e.g., reports:edit). They can be configured in the same Roles dashboard screen. If you are not sure if you need to use permissions or only roles suffice, see Your apps’s authorization strategy.

Roles have priorities which are used when a user is provisioned from multiple sources with conflicting roles. If this happens then the role with the highest priority will be assigned to the user. To edit the priorities select “Edit priority” and drag-and-drop the roles you want higher or lower.

Set the default role

Each environment you have at WorkOS has a default member role, which is automatically assigned to every new user profile. The default role cannot be deleted, but you can set any other role as the default.

To change the default role, navigate to the Roles section of the WorkOS dashboard, select the role you want to set as default, and click “Set as default”.

Role assignment using SCIM

If you are using SCIM-compliant and Google Workspace directories, you can assign IdP groups to role data in your app using WorkOS.

To do the mapping, go to the WorkOS dashboard → Organizations → select organization → click “View directory“ in the Directory Sync section → scroll down to ”Role assignment“ → click ”Configure role assignment“. Now you can add a mapping between the directory’s groups and your app’s user roles.

In the example below, the directory group “Engineering” is mapped to the role “Developer” in our app, which is assigned to one user.

From the point you add a new mapping, all new users added to the directory group will be given the mapped role from the WorkOS API. The role will be in the directory user response. This is what the payload would look like for the example we saw above: a user that is part of the Engineering directory group and was automatically assigned the Developer role in your app.

	
const user = {
  id: 'directory_user_01E1JG7J09H96KYP8HM9B0G5SJ',
  idpId: '2836',
  directoryId: 'directory_01ECAZ4NV9QMV47GW873HDCX74',
  organizationId: 'org_01EZTR6WYX1A0DSE2CYMGXQ24Y',
  firstName: 'Marcelina',
  lastName: 'Davis',
  jobTitle: 'Software Engineer',
  emails: [
    {
      primary: true,
      type: 'work',
      value: 'marcelina@example.com',
    },
  ],
  username: 'marcelina@example.com',
  groups: [
    {
      id: 'directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT',
      name: 'Engineering',
      createdAt: '2021-06-25T19:07:33.155Z',
      updatedAt: '2021-06-25T19:07:33.155Z',
      rawAttributes: {},
    },
  ],
  state: 'active',
  createdAt: '2021-06-25T19:07:33.155Z',
  updatedAt: '2021-06-25T19:07:33.155Z',
  customAttributes: {
    department: 'Engineering',
  },
  rawAttributes: {},
  role: { slug: 'developer' },
};
	

Outsource the role assignment to admins

You don’t have to do the mapping yourself. You can instead allow IT admins to assign roles to groups during directory setup using the Admin Portal. 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.

Alternative: custom-mapped attributes

If your customers do not use groups to establish and manage user roles, but instead assign roles using attributes on individual users, you can use custom-mapped attributes.

You can create a custom-mapped attribute role (e.g., myRole) in the WorkOS Dashboard → Directory Sync → Custom-mapped attributes. Each attribute can be required or optional.

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. This is what a user profile for this example could look like:

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

Role assignment using SSO

IdPs usually assign users to groups. Groups usually correspond to roles in your app.

When a user logs in, the IdP sends over their identity provider group memberships 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.

To do the mapping, go to the WorkOS dashboard → Organizations → select organization → click “View connection“ in the Authentication section → scroll down to ”Groups and role assignment“ → click ”Create group“. Now you can add a mapping between the IdP groups and your app’s user roles.

In the example below, the IdP group “engineering” is mapped to the role “Developer” in our app, which is assigned to one user.

Every time a user from the “engineering” IdP group signs in, they will be assigned the role “developer” (as long as there is no other highest priority group membership), and this will be reflected in the SSO user profiles that WorkOS returns to your app.

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

Which option is right for you?

SSO role assignment has some drawbacks:

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

Because of these restrictions, if you use a directory, it is recommended that you use SCIM role assignment.

If you do use a directory but your customers do not use groups to establish and manage user roles, but instead assign roles using attributes on individual users, you can use custom-mapped attributes.

No matter how you choose to implement role mapping, WorkOS has your back. With SDKs for every popular platform, and Slack-based support, you can implement SSO and Directory Sync in minutes rather than weeks. WorkOS supports every protocol and every major IdP, and the Admin Portal takes the pain out of onboarding your customers’ IT teams and configuring your app to work with their identity provider. And on top of all these, unlike competitors who price by monthly active users, WorkOS charges a flat rate for each company you onboard — whether they bring 10 or 10,000 SSO users to your app.

‍Sign up for WorkOS and start building today.