Permissions, Permission Groups, and Permission Boundaries

Permissions

A permission is a specific access right or privilege that defines an allowable action or operation on a resource within an application. They offer finer-grained access control compared to just relying on roles alone and determine what users or machines are allowed to do, such as reading, writing, creating, deleting, or performing other actions. Permissions can be assigned to both roles and permission groups to control access to actions and resources.

🚧

No Tenant-level Permissions

Wristband does not support creating permissions at the Tenant level. Permissions can only be created at the Application level.

Permission Accumulation

Wristband adheres to the concept of permission accumulation, also known as additive permissions. This is the practice of combining permissions when multiple roles are assigned to a subject. In Wristband, when a user or M2M client has multiple roles assigned to them, their effective permissions are the combined sum of the permissions from each of those roles.

For example, if a user is assigned the following roles with the associated permissions:

• Role A: Read, Write
• Role B: Write, Delete

When the user is assigned both Role A and Role B, their effective permissions would be the combination of permissions from both roles, resulting in the following effective permissions:

• Read (from Role A)
• Write (from Role A and Role B)
• Delete (from Role B)

So, the user can read, write, and delete based on the additive permissions from their roles.

Structuring Permission Values

The format of a new custom permission is a flexible string value that you can imbue with any semantics you desire. You have the liberty to shape this string in a manner that aligns with the access control needs of your application. If your application's resource access needs are straightforward, then the string can be devoid of any specific structure. Conversely, for applications with a more intricate array of resources and actions, employing colon notation can bestow additional structure upon your permissions.

For instance, within Wristband, we expose predefined permissions that adhere to a structured format of <resource>:<action>. Consider the User entity defined in Wristband. To achieve granular control over various actions involving a user, we establish multiple permissions following the aforementioned structure. For instance, to access and read data associated with a Wristband user, the user:read permission is required. To delete a user, the user:delete permission is required.

Permission Types

There are two types of permissions in Wristband: custom permissions and predefined permissions. Both can be assigned to roles and permission groups.

Custom Permissions

Custom permissions are specific to your application's business logic. Depending on how you structure the custom permission value, it can logically represent an action, a resource, an action on a specific resource, or just about anything else you want. These permissions only have meaning to your application and are not able to be applied to any Wristband resources or APIs. Custom permissions can be created, modified, and deleted at any time.

Predefined Permissions

Predefined permissions are pre-created and managed for you by Wristband, and these permissions cannot be created, modified, or deleted. They apply only to Wristband resources and APIs.

Permission Groups

If you have a common set of permissions that you want to assign to multiple roles, you can create a permission group consisting of multiple individual permissions. From there, the permission group can be assigned to the role instead. This offers greater administrative convenience since you don't have to repeat the assignment of each individual permission to every role. Both individual permissions and permission groups can be assigned to the same role simultaneously.

The principle of permission accumulation also applies when permission groups are involved.

Application-level vs Tenant-level Permission Groups

Permission groups can be created at both the Application level and the Tenant level. Roles can have a combination of permission groups assigned to them, where some assigned permission groups exist at the Application level while others exist at the Tenant level.

Application Permission Groups

Permission groups defined at the Application level can be assigned to roles in any tenant in the entire application, except in cases where the permission group's Tenant Visibility is restricted to certain tenants (more on that below).

Tenant Permission Groups

Permission groups defined at the Tenant level can only be assigned to roles that belong to the same tenant in which the permission group was created. This is useful if one customer using your application needs additional access controls specific to their business context without exposing it to other customer tenants.

Tenant Visibility

When defining a permission group at the Application level, you can specify which tenants a permission group should be visible to. "Visible" means that a permission group can be assigned to roles owned by a particular tenant. If a tenant does not have visibility on a permission group, then the admins of that tenant cannot assign the permission group to roles within that tenant. The following options are supported by Wristband:

Tenant-level Permission Groups and Visibility

For any permission group defined at the Tenant level, Wristband will always set the visibility to Owner. The Owner visibility means that the permission group is only visible to the tenant that owns it.

Permission Boundaries

Permission boundaries are an optional entity that can define the reach of access for a user's or M2M client's resolved set of assigned permissions. Permission boundaries can only be assigned to roles and permission groups. If you need a role that has permissions with different permission boundaries, then you need to use permission groups. You can create multiple permission groups with different permission boundaries and then assign them to a single role.

No Tenant-level Permission Boundaries

Wristband does not support creating permission boundaries at the Tenant level. Permission boundaries can only be created at the Application level.

Permission Boundary Types

Wristband supports the following permission boundary types:

Predefined Permission Boundaries

Predefined permission boundaries are pre-created and managed for you by Wristband, and these boundaries cannot be created, modified, or deleted. They apply only to Wristband resources and APIs. Wristband provides the following predefined permission boundaries that your application may need:

For example, let's say there is a user in your application. That user has a role assigned to them, and that role has been assigned the Read User permission (user:read). Depending on which permission boundary the role has assigned to it, the scope of which the Read User permission applies changes.

In this scenario, each boundary implies the following:

• Self: This user can only fetch user data for their own user and no one else, not even other users in the same tenant.
• Tenant: This user can fetch user data for all users that live in the same tenant as themselves, but they cannot fetch user data for users in other tenants.
• Application: The user can fetch user data for all users in the entire application.

Permission boundaries are additive. When resolving the permissions for a user or M2M client during an authorization check, it is possible that the same permission is associated with more than one role or permission group. If those roles or permission groups have different permission boundaries applied, then the widest boundary will be applied for that single permission.

In the example above, let's say the user had an Admin User role with a predefined permission boundary value of Application as well as an End User role with a predefined permission boundary value of Self. Both roles have the Read User permission assigned to them. The resolved scope of the user's Read User permission access will be the Application permission boundary since it has a wider boundary than Self. The end result is that the user would be able to fetch user data for users across the entire application.

Permission Boundaries with Tenant Inclusion/Exclusion Lists

Permission boundaries with a tenant inclusion list or exclusion list allow you to define which tenants have access to permissions associated with a role or permission group. This is useful for cases where there are back-office admins or account reps who manage customers using your application. The admins of your application may want to limit the tenants in production that these personas can access.

With a tenant inclusion list, the permissions will only be applied to tenants that fall in the list and not applied to any other tenant in the application. For example, imagine a team of customer account managers responsible for managing only a subset of customer tenants: Tenant A and Tenant B. You could create a permission boundary using a tenant inclusion list of Tenant A and Tenant B.

In this scenario, the customer account managers would only have access to those two tenants and no other tenants in the application. Conversely, permissions will not be applied to any tenants that fall under a tenant exclusion list, though all other tenants in the application would have permissions applied.

Custom Permission Boundaries

Custom permission boundaries are specific to your application's business logic. These are useful when you want to mimic the ability of the other permission boundary types above with your own application-specific context on how permission boundaries are scoped. Custom permission boundaries can be created, modified, and deleted at any time.