Roles

Overview

Roles provide a way to organize and manage access to your application's resources by grouping related permissions together. Wristband allows you to define roles and assign them to users and OAuth2 clients.

Both users and clients can be assigned multiple roles, allowing them to access different resources and perform different actions based on their responsibilities.

While Wristband manages role definitions and assignments, your application is responsible for enforcing authorization by evaluating an authenticated user's or client's roles and permissions when accessing protected resources.

Role Assignments

Roles can be assigned to both users and OAuth2 clients. Each entity can have one or more roles, depending on the level of access it requires.

Assigning Roles to Users

Users can be assigned roles based on their responsibilities within your application.

For example:

• Single Role: A user assigned the Manager role can access employee records and management reports, while a user assigned the Sales Representative role can access sales-related functionality.
• Multiple Roles: A user assigned both the Manager and Financial Analyst roles can access management functionality as well as financial data.

Assigning Roles to OAuth2 Clients

OAuth2 clients can also be assigned roles to control which resources and operations they are authorized to access.

For example:

• Microservices: Assign roles to control which backend services or APIs an M2M client can access.
• Scheduled Jobs: Assign roles to define which operations automated jobs and background processes are permitted to perform.

Role Types

Wristband supports two types of roles: Custom Roles and Predefined Roles.

Custom Roles

Custom roles are roles that you define and manage based on your application's authorization requirements. You can create, modify, or delete these roles as your application's access-control needs evolve.

Custom roles can be created at either the application level or tenant level, allowing you to define roles that are shared across tenants or specific to an individual tenant.

Predefined Roles

Predefined roles are managed by Wristband and cannot be modified or deleted. These roles grant access to Wristband-managed APIs and resources rather than your application's own resources.

For example, assigning the Application Admin Client role to an OAuth2 client grants it administrative access to application-level resources managed by Wristband.

Application-Level vs. Tenant-Level Custom Roles

Custom roles can be created at either the application level or tenant level. The level at which a role is created determines which entities can have that role assigned to them.

Application-Level Roles

Application-level roles can be assigned to application-level OAuth2 clients, as well as users and clients belonging to individual tenants.

The role's Tenant Visibility configuration determines which tenants can assign the role to their users and clients. The following visibility options are available:

• All: The role can be assigned to users and clients across all tenants within the application.
• Tenant Inclusion List: The role can only be assigned to users and clients belonging to the specified tenants.
• None: The role can only be assigned to application-level OAuth2 clients and cannot be assigned to users or clients belonging to any tenant.

Regardless of the Tenant Visibility configuration, application-level roles can always be assigned to application-level OAuth2 clients.

Tenant-Level Roles

Tenant-level roles are defined within a specific tenant and can only be assigned to users and M2M clients belonging to that tenant.

These roles allow individual tenants to define their own access-control requirements without making those role definitions available to other tenants.

Role Assignment Policies

Role Assignment Policies allow you to automatically assign default roles to users during specific lifecycle events, such as signup or provisioning through an external identity provider (IdP).

To configure these policies, log in to your account and use the following path:

1. Navigate to the Application View of the Wristband dashboard.
2. Select Authorization from the side menu.
3. Click on Assignment Policies.

The following policies are available:

• Default Signup Roles: Roles automatically assigned to users during signup. This is particularly useful for B2B applications where the first user to create a tenant needs elevated permissions, such as an Owner role, to manage their organization's environment.
• Default IdP User Sync Roles: Roles automatically assigned to users when they are provisioned or synchronized through an external identity provider (IdP). These default roles are applied in the following scenarios:
  • Initial Provisioning: A user is provisioned through Just-in-Time (JIT) provisioning, and either Role Mapping is disabled, or their group memberships do not match any configured Role Mapping rules.
  • Subsequent Logins: Role Mapping is enabled, and a user's updated group memberships no longer match any configured Role Mapping rules.

Tenant-Level Overrides

By default, tenants inherit the application's Role Assignment Policies. However, you can override these policies for individual tenants that require different role assignment configurations.

To configure a tenant-level override:

1. From the Application View, select the desired tenant using the Tenant dropdown in the side navigation menu.
2. Navigate to Authorization → Assignment Policies.
3. Select the Edit Tenant Config tab.
4. Enable the tenant override toggle.