User Permissions in the Main API

BrightSign Network Entities

The following BrightSign Network entities use permissions:

Person

The root entity representing a single physical person with a specified login (in email format) and password. Person is created once during new customer signup and grants very limited access to BSN.

Network

An entity representing a company, organization or other group of people with their content and infrastructure.

Role

The entity of a network, aggregating permissions which are common for the members of some company department. For example:

• User: The entity-relation between person and network allowing multiple people to be the member of the same network as well as the same person be the member of any number of networks. It may optionally be a member of one role and inherit its permissions.

• Operation Permission: The entity-relation which defines the kind of access the current role has for the current business operation. It applies to all instances of the target entity type but has low priority

• Object Permission: The entity-relation which defines the kind of access the current user or role has for the current business operation under the current entity instance. It does not affect other entities of the type but has higher priority than operation permission.

User Permission Model

In the root of the user permissions model, there are 300+ business operations organized into tree. Each of them describes some case the actor may perform in the system and is classified by target entity type and visibility level. Business operations associated with the same entity type form a single branch headed by the "{Entity Name} Full Control" business operation. Not all entities may be controlled by object permissions: Some like subscriptions are controlled only by operation permissions and simple entities like BrightWall Configuration are not integrated into user permissions model at all and are accessible to everyone.

By principal type, the permissions are classified as role permissions, associated with either system or custom roles, and user permissions, associated with some person-in-network. The role permissions are fully-functional while user permissions are limited and can define access only to specific entity instances. Otherwise, the permission can also be marked as "Fixed" which makes it not editable or overridable for all users. And, of course, it can either grant or revoke access to a specified business operation.

The priorities of the described permissions types are as follows (from lowest to highest):

1. Role permission for the parent business operation

2. Role permission for the current business operation

3. Role permission for the parent business operation under the parent entity

4. Role permission for the current business operation under the parent entity

5. Role permission for the parent business operation under the current entity

6. Role permission for the current business operation under the current entity

7. User permission for the parent business operation under the parent entity

8. User permission for the current business operation under the parent entity

9. User permission for the parent business operation under the current entity

10. User permission for the current business operation under the current entity.

Note that only the Content entity type has parent entity type of Content Folder. However, folders may be implemented in the same way for Live Text Feeds, Live Media Feeds, Dynamic Playlists, Tagged Playlists, and Presentations.

Retrieving Operations 

The Main API currently provides the complete set of methods required for retrieval and management of permissions of all types but separately.

To retrieve the business operations tree and all operation permissions:

GET ~/2020/10/REST/Operations/Root/{*path}
GET ~/2020/10/REST/{EntityName}/Operations/

Retrieving Object Permissions

The object permissions granted to a given user may be retrieved by general user retrieval methods and specifically:

GET ~/2020/10/REST/Self/Users/{id:int}/Permissions/

GET ~/2020/10/REST/Users/{id|login}/Permissions/

The operation and object permissions granted to a given role may be retrieved in similar way by general role retrieval methods and specifically:

GET ~/2020/10/REST/Roles/{id|name}/Permissions/

GET ~/2020/10/REST/Self/Users/{id:int}/Role/Permissions/

All entities called "securable" which support object permissions have their own [Permission[]] Permissions collections which are always initialized by all corresponding entity retrieval methods. This group of resources also provides that information:

~/2020/10/REST/{SecurableEntityName}/{entityId}/Permissions/

Business Operation Permissions

Each business operation has a UID which does not change during its lifetime and is intended to be used in checks on the client side. But they may be reassigned to a different parent based on changes in business requirements and new features. For performance reasons, the specified resources and collections contain permissions assigned only on the current level.

Permissions priority levels follow these general rules:

• Network-wide operation permissions are the lowest priority.

• Role-object permissions are the next-highest priority. Depending on the content, they may also be granted on the parent folder and the content itself.

• User-object permissions granted on a parent entity have higher priority than role-object permissions granted on the same parent entity. So first calculate the inheritance on the parent entity, and then on the child entities.

Permissions Retrieval Order and Priorities

To determine whether the user may perform a specified business operation under the given entity instance, the client application must:

1. Retrieve the business operations tree

2. Determine whether the given user is a member of some role, and if so, retrieve the corresponding role operation permissions.

3. Determine whether the given entity has some parent entity, and if so, retrieve the role object permissions of the parent entity.

4. Map the role object permissions of the parent entity on the role operation permissions

5. Retrieve the user object permissions of the parent entity

6. Map the user object permissions of the parent entity on the role object permissions of the parent entity and role operation permissions

7. Retrieve the role object permissions of the current entity

8. Map the role object permissions of the current entity on the user object permissions of the parent entity and the role object permissions of the parent entity and role operation permissions

9. Retrieve the user object permissions of the current entity

10. Map the user object permissions of the current entity onto the role object permissions of the current entity, and the user object permissions of the parent entity, and the role object permissions of the parent entity and role operation permissions (step 4 + step 6 + step 8)

11. Calculate the permissions inheritance according to the business operations tree

12. Find and check the permission for the specified business operation in the resulting tree.

Other Information

• The business operations tree only gets updated upon a BSN release.

• All user and role operation permissions may be retrieved in one call.

• Only the content current has a parent entity currently.

• The entity permission collections contain all related user and role object permissions.

• If there are no permissions in a given case, the access may be determined as undefined.