Roles

Roles simplify access control by grouping similar privileges that either a user or machine requires to interact with your application. Admins can assign or revoke roles using the Wristband dashboard. Proper access control is enforced by the application using roles (and permissions) during runtime.

Users and machines (M2M OAuth Clients) can have multiple roles, providing a flexible and fine-grained access control mechanism. This is useful in complex organizations where individuals may require access to various resources and functionalities.

Role Relationships

Assigning Roles to Users

Users can have one or more roles based on their responsibilities.

Example: One Role per User

• A "Manager" may access employee records and reports, while a "Sales Representative" may access sales data.

Example: Multiple Roles for One User

• A user with both "Manager" and "Financial Analyst" roles can access managerial functions and financial data.

Assigning Roles to Machine-to-Machine OAuth Clients

M2M clients can also have roles to control their access to resources and actions.

Example: Microservices

• Control which microservices can access each other and their actions.

Example: Batch Processing or Scheduled Jobs

• Define what scheduled jobs are allowed to do.

Role Types

Custom Roles

Custom roles are specific to your application's business logic. They can be created, modified, and deleted as needed.

Predefined Roles

Predefined roles are managed by Wristband and cannot be modified. They apply only to Wristband resources and APIs. An example is the Application Admin Client role for granting M2M clients access to all application resources.

Application-level vs Tenant-level Custom Roles

Custom roles can be created at both the Application and Tenant levels. Users and M2M clients can have roles from both levels.

Application Roles

Roles defined at the Application level can be assigned to users in any tenant, except where the role's Tenant Visibility is restricted.

Tenant Roles

Roles defined at the Tenant level can only be assigned to users or M2M clients in that tenant. This allows for specific access controls without exposing them to other tenants.

Tenant Visibility

When defining an Application-level role, specify which tenants can see the role:

For Tenant-level roles, visibility is always set to Owner, meaning only the owning tenant can see the role.

Role Assignment Policies

Role Assignment Policies allow you to define default roles that are automatically assigned to users when certain events occur. They can be configured under Authorization → Assignment Policies in the Application View of the Wristband Dashboard.

Available policies include:

• Default Signup Roles: Roles automatically assigned to a user upon signup. This is useful for B2B applications where the first user to sign up for a tenant often requires elevated permissions, such as an Owner role, to manage the tenant on behalf of their organization.
• Default IdP User Sync Roles: Roles automatically assigned to a user when they are synced from an external identity provider. This applies during JIT provisioning flows and when roles are synced on login. Note that these defaults are only applied if no other role assignments with higher precedence exist. For example, if Role Mappings are configured for the user, those take priority and the default roles will not be assigned.

Role Assignment Policies can also be overridden at the tenant level under Authorization → Assignment Policies in the Tenant View of the Wristband Dashboard.