Role Mapping

Wristband lets you map roles or security groups assigned in a customer's identity provider to custom roles in your application during enterprise SSO login. This ensures users get the right level of access based on their organizational role.

Security Benefits of Role Mapping

Many organizations require role mapping for any SaaS app used by their employees, and requirements are driven by internal IT and/or CISO policy. Wristband's role mapping capabilities help maintain a consistent implementation across applications:

• Least Privilege Principle: Users get only the access required for their job function, limiting the blast radius of a compromised account.
• Efficient User Lifecycle Management: Access stays in sync with each login, so role or security group changes in the identity provider carry through to your application automatically, with no manual reconfiguration.
• Audit Trails and Compliance: Access ties directly to roles, giving you a clear trail to support compliance requirements and internal policy reviews.
• Centralized Control: Managing access through role mapping keeps permissions consistent across your application and others the organization uses.

How Role Mapping Works

Role mapping requires Just In Time (JIT) Provisioning to be enabled for the enterprise external identity provider. On login, Wristband fetches the user's roles or security groups from the identity provider and assigns the corresponding Wristband roles, so users get the right access from their very first login.

Establishing Roles in the External Identity Provider

To enable role mapping for an external identity provider (IdP) in one of your Wristband tenants, start by configuring the IdP from its administration console. This assumes you've already set up application integration in the provider for SSO login with Wristband.

Create groups for the relevant organization in the IdP. For example, to use Microsoft Entra ID for SSO login with JIT provisioning and role mapping, you'd establish a security group in the Azure admin console.

Once your groups are set up, configure your SSO application in Entra to declare a groups optional claim so group information is returned in the ID token. Wristband requires this claim to map groups to roles in your application.

Mapping Roles in Wristband

Setting up roles in the external identity provider is only a part of the process to enable role mapping. You also need to use the Wristband dashboard to associate groups with specific Wristband roles.

Navigate to Tenant View in the Wristband dashboard and select the Identity Providers -> Enterprise option from the side navigation. Once there, you can find and select your enterprise IdP to update configurations.

Here, you would map each group name to your desired Wristband role. It is possible to map a single group name to more than one Wristband role at a time.

Role Assignment During JIT Provisioning

JIT provisioning must be enabled on your enterprise external identity provider for role mapping to take effect. When a user is JIT provisioned, Wristband assigns roles based on the groups retrieved from the identity provider at the time of authentication, so access stays aligned with the user's current group membership.

For example, if you've included the roles claim in your authorization request to the Wristband Authorize Endpoint, a successful JIT provisioning login returns an access token that reflects the mapped roles. You can use that token to call the Wristband UserInfo Endpoint, and the response will include the mapped roles.

{
  "sub": "y7ng4dlhcnfiddbz2tifv73ivu",
  "tnt_id": "kh643sdf5ze6zcqb2e25dm5w6u",
  "app_id": "m7k55onh6nbsjggayhubbef4eq",
  "idp_name": "wristband",
  "roles": [
    {
      "id": "xhmwelq5fjetfmugxtwdy5oziy",
      "name": "app:yourapp:admin",
      "displayName": "Admin"
    }
  ]
}

Default User Sync IDP Roles

Default roles give users a fallback set of access permissions during JIT provisioning when they don't have an explicit group or role assignment from the identity provider. You can configure a default user sync IdP role assignment policy in the Wristband dashboard, so users still get the appropriate roles even without a mapped group.

Refer to the Role Assignment Policies documentation to learn how to configure this for your application.