Launch Week Day 2: Roles

Roles are defined by sets of permissions that determine the types of actions a user can perform. Typically, roles are assigned based on users’ job functions, responsibilities, or other required tasks. 

For instance, users for an application might be categorized into the following groups: admin, developer, and support. The "developer" role needs access to API keys, whereas the "support" role does not require this and should be provisioned with restricted access. In turn, developers shouldn’t be able to edit critical settings, while this permission should be reserved for admins.

Authentication (“AuthN”) ensures that a user is whom they claim to be, whereas authorization (“AuthZ”) determines what the user can see and do. Roles provide a foundation for AuthZ, allowing you to provision your users according to the roles that you specify within the WorkOS dashboard.

Best of all, Roles are free to all WorkOS users because we view both authentication and authorization as crucial building blocks for building any type of SaaS app. Whether you are just getting started or maturing your product into an enterprise offering, secure logins and access control are fundamental capabilities that should not be compromised.

Let’s see how it works.

Creating roles is as easy as a few clicks in the dashboard. You can specify the name, slug, and a description for each role. While the description and name can be edited later, the slug is immutable and can’t be changed.

Sessions now have this information automatically enabled for all users of WorkOS.

After creating your specific roles, you can assign them to your users. If not specifically assigned, all users will have the default role of “member.”

Integrating Roles

Once roles have been added and defined in the dashboard, they can be easily used with the WorkOS SDKs. When using the familiar Authenticate with code API endpoint, you now receive a `role` claim within the access token, which is a new parameter which we launched yesterday as part of Sessions.

Using this `role` claim, you can provision user access to your app by decoding the JWT:

      
import * as jose from 'jose'

const { user, accessToken } = await workos.userManagement.authenticateWithCode({
  clientId: 'client_123',
  code: '01E2RJ4C05B52KKZ8FSRDAP23J',  
});
const { role } = jose.decodeJwt(accessToken)

switch (role) {
  case: 'admin':
    // Provision access to admins, usually means access to everything
    break;

  case: 'developer':
    // Provision access to developers, e.g. can view test API keys and logs
    break;

  case 'support':
    // Provision access to support roles, e.g. can view logs
    break;

  default:
  case 'member':  
    // Provision default access in case no role other than the default "member" is applied to user
    break;
}
        
      

Accessing the role is also possible without the use of WorkOS Sessions:

      
const organizationMembership = await workos.userManagement.getOrganizationMembership(
'om_01E4ZCR3C56J083X43JQXF3JK5',
);
const role = organizationMembership.role.slug;

switch (role) {
  case: 'admin':
    // Provision access to admins, usually means access to everything
    break;

  case: 'developer':
    // Provision access to developers, e.g. can view test API keys and logs
    break;

  case 'support':
    // Provision access to support roles, e.g. can view logs
    break;

  default:
  case 'member':  
    // Provision default access in case no role other than the default "member" is applied to user
    break;
}

        
      

For more information on Roles and how to use them, check out the documentation.

Coming soon: Role Mapping

Currently, obtaining reliable user role information from Identity Providers (IdPs) is highly fragmented. Administrators have the option to map roles through either SAML or SCIM protocols, using attributes or groups. However, consistently applying these mappings across the unique workflows of different IdPs presents its own set of challenges.

Role-based authorization is critical for access control, ensuring users only reach role-relevant resources. A flawed role mapping from the IdP to applications can cause significant security breaches, from exposing sensitive data to unauthorized access.

WorkOS is ideally positioned to streamline the role mapping process, facilitating secure and seamless access to accurate role information from IdPs. This feature allows for role information to be efficiently derived from IdP groups, where users inherit roles based on their group membership. In scenarios where users belong to multiple groups with varying roles, the system intelligently assigns the highest priority role to the user. This approach ensures a coherent and hierarchical framework for distributing roles within an organization, optimizing both security and operational efficiency.

Organization level defaults

Every organization member is automatically assigned the `member` role by default. This default setting can be modified later to better align with your application's specific requirements.

Currently, defaults are set at the environment level. Defaults at the organization level are coming soon.

That’s day two of Launch Week. Tune in tomorrow - we’ll be unveiling a new way to process your WorkOS data.

‍