We're updating some of our product names. K2 Five will soon be Automation On-Prem. You may see both product names in our help pages while we make this change.

Authorization Framework Overview

To protect your applications from unauthorized use or unauthorized modification, you may want to control or restrict access to certain K2 application elements (e.g. Forms, Views, SmartObjects) or Categories in your environment. The Authorization Framework allows you to do this, by configuring various levels of rights on elements in your K2 environment. Use this topic to become familiar with the Authorization Framework, the features of the framework, and best practices to use the framework to secure your K2 applications.

On a high level, you can think of the authorization framework as a collection of Roles (people) that have certain rights on Objects (Categories, Views, Forms, and SmartObjects) in a K2 environment. You can control access to different K2 roles by configuring security on a role, and control access to objects by assigning rights to a role to interact with K2 objects. Permissions are used to define explicit authorization, and inheritance/overrides.

Let’s use an example: suppose that you have a Category called “Human Resources” in your organization, which contains various Forms and Views used in HR applications. You may want to give the “HR App Builders” Role the View, Create, Modify and Delete rights on the “Human Resources” Category so that users in this role can see, create, edit and delete items within that category when they are using K2 Designer to build applications. Then, you may want to give the “HR Administrators” Role the Execute right on the “Human Resources” Category so that users in the “HR Administrators” role can see and run the Views and Forms stored in the “Human Resources” category at runtime.

Consider the diagram below, which explains the relationships between components of the Authorization Framework. The blue boxes represent Roles and the rights that users might have to administer Roles. (Note that the membership of a Role could include Users and Groups). The Security defined on a Role determines who is able to modify the membership of a particular Role, and who may delete a particular Role. The green boxes represent the objects where you can set Rights. Objects that you can protect by applying Rights include Categories, Views, Forms and SmartObjects. You can set View (this is a design-time right that controls who may view those items in K2 Designer), Create (this is a design-time right that controls who can create K2 artifacts such as categories (folders), SmartObjects, Views, and Forms in K2 Designer), Modify (this is a design-time right that controls who can edit, rename and move objects in the K2 Designer), Execute (this is a runtime right that determines who can run that object, or the items contained in that category) and Delete(this is a design-time right that controls who can delete objects in the K2 Designer and K2 Management) rights. As the creator of objects you can assign Security rights to them, which allows others to manage the object's security, including assigning View, Create, Modify, Execute, Delete and Security rights.

Roles

Roles can contain Users and Groups. If you wanted to define authorization for something in your K2 environment, you would normally create a Role first, and then assign members to that role by adding Users and Groups to the Role. (Eventually, you will give this role rights on the items they should have access to). You can manage the security of editing K2 roles by granting Modify permission to users who should be able to add or delete users from a role, and granting Delete permission to users who should be allowed to delete that role.

By default, three system roles are created during installation, but you can create as many additional ones as needed. Note that the default Roles cannot be deleted.

Default K2 Roles
Role	Description
Security Administrators	Any person needing to assign permissions to K2 objects must be a member of this role Members of this role always have View rights on K2 Objects and Modify and Delete rights on roles ensuring that they can never be locked out of any object in the system The Security Administrators role does not display when clicking on the security button in Management Site > Roles, because this role’s security cannot be edited Created at installation and automatically includes the admin account specified in the installer. Security Administrators can modify the membership of the role but cannot delete it There must always be at least one user in this role The role can contain users and groups Default permissions for the Security Administrators role are Create, Modify, View, Execute, Delete or Security rights. The modify and delete rights are assigned on roles, while all rights are assigned on objects such as SmartObjects.
Package and Deployment	Members of the Package and Deployment role have view and modify rights to all objects in the system. This allows them to package and deploy objects. Any person in this role needs modify rights on the objects that need to be overwritten during deployment. Any person needing to package or deploy K2 solutions must be a member of this role. If a person in the Package and Deployment role has been denied view rights to a specific object, they will see an error message during packaging or deployment. If a person in the Package and Deployment role has been denied modify rights to any category in the SharePoint 2013 sub-tree, they will see an error on deployment after selecting the package and pressing the OK button. This is because the SharePoint name inference process may have to move objects after creating them if they are deployed to a different site collection or environment. Default permissions for the Package and Deployment role is View, Create and Modify rights assigned on objects such as SmartObjects.
Everyone	The Everyone role contains all authenticated users for all security labels on the system This role is created during installation This role cannot be modified or deleted The role cannot be deleted Anonymous users are not included in the role Default permissions for the Everyone role are View, Create, Modify, Execute, and Delete rights. The modify and delete rights are assigned on roles, while view, and execute rights are assigned on objects such as SmartObjects. Create rights are assigned to Categories (Allows a user, group or role to create category folders and K2 artifacts in a category) At installation, the Everyone role is added by default to all K2 objects with View, Modify and Delete rights.

Security Rights on Roles

Security rights on roles determine who may edit and delete a Role.

Right	Description	Applies To	Assigned by
Modify	Allows you to add and remove users and groups to a role and the change the description of a role.	Roles	Role Creator or Security Administrators
Delete	Allows you to delete the role	Roles	Role Creator or Security Administrators
Security	Allows you to assign rights to a role	Roles	Role Creator or Security Administrators

Custom Roles

You can create custom roles and assign security to people who should be allowed to manage the role. As the role creator, you automatically get Modify, Delete, and Security rights on the role. When you create a new role, the Everyone role automatically inherits modify and delete rights.

For more information on creating roles and setting security on roles, see Roles.

K2 Objects

You set rights on K2 objects to allow people in your organization to view the object in the category tree and use the object either at runtime or design time. The following table lists the objects and the corresponding rights that you can set. Keep in mind that View, Create, Modify, and Delete are design time rights, and Execute is a runtime right.

Objects	Rights
Forms	View Modify Execute Delete Security
Views	View Modify Execute Delete Security
SmartObjects	View Modify Delete Security
Categories	View Create Modify Execute Delete Security
K2 Workspace (Mobile) Apps (Forms)	Execute
K2 Workspace (Desktop) (My Forms)	Execute
Package and Deployment	View (must use Package and Deployment role and have View rights on all objects that will be packaged) Create (used during deployment of a package, users in the Package and Deployment role get create rights) Modify (for deployment you must have Modify rights when creating new versions of deployed objects. If deploying SharePoint objects, Modify rights are required on all categories under the SharePoint 2013 Folder in the category tree)
K2 Designer	View Security
Workflow Steps	View Security

You can move objects around in a category by copying and pasting or by performing a direct move. Rights are required to perform these actions.

Copy and pasting objects to a different category requires View rights on the object to be copied, and View rights on the destination category.
Moving objects to a different category requires:
- Security rights to the object
- Modify rights on the source and destination categories
To see objects or sub-categories in a category you must have View rights on that category

Rights on K2 Objects

When defining rights on K2 Objects, first determine which roles can browse to that object in the category structure and modify the object using K2 Designer, and assign the roles the View and Modify right. You can use the category node in the K2 Management Site to do this or you can use the context menu in K2 Designer.

While it is possible to give Users and Groups rights directly on K2 Objects, you should preferably create roles, and then assign rights to roles, because this will make subsequent security administration easier.

Right	Description	Implemented on	Assigned by
View	Allows you to see and use items at design time	Categories, Forms, Views, SmartObjects	Security Administrators
Create	Allows you to create categories (folders) and K2 artifacts such as SmartObjects, views, and forms in K2 Designer.	Categories	Security Administrators
Modify	Allows you to update (for example edit, rename, move, create associations and package and deploy) items at design time	Categories, Forms, Views, SmartObjects	Security Administrators
Execute	Allows you to use items at runtime	Categories, Views and Forms You cannot execute a category, but you set execute rights on the category so that the child objects inherit the right to execute forms in the category. SmartObjects do not expose runtime rights. Security is controlled through Execute rights at the View and Form level.	Security Administrators
Delete	Allows you to delete items in K2 Designer and K2 Management.	Categories, SmartObjects, Views, and Forms	Security Administrators
Security	Allows you to give other people the right to assign rights on a specified item.	Categories, SmartObjects, Views, and Forms	Person creating the object or Security Administrators

Permissions

Permissions are used to specify the behavior of rights on objects. Permissions allow or deny roles, users, and groups the ability to perform a right. Or, to put it differently: Rights define what you can do, Permissions define whether you are allowed to do it.

Consider our hypothetical “Human Resources” example, and suppose that we have a Form called “Ratings” that you want to protect. You may want to Execute > Allow “HR Admins” the Execute right on the Rating Forms so that members of that role can run the Form, but for all other users the permission should be Execute > Deny, so that other users are explicitly denied the ability to run that sensitive Form.

Permissions	Description
Allow	Explicitly grants the ability to perform an action.
Deny	Explicitly prevents the ability to perform an action. Note: Deny takes precedence over all permission settings.
None	Implicitly prevents the ability to perform an action. Can override this permission further down in the category/sub-category.
Inherited Allow	Implicitly grants the ability to perform the action based upon settings further up the category tree.
Inherited Deny	Implicitly prevents the ability to perform the action based upon settings further up the category tree. This permission cannot be changed.

You must have Security rights to assign Permissions. Members of the Security Administrators group and the creator of an object by default get Security rights. You can also assign Security rights to other roles as required.

About Inheritance

Inherited permissions are permissions passed down from the parent object to the child objects, making it easier to manage permissions. You can break inheritance or turn inheritance back on if previously broken. By default, rights are inherited.

Inheritance	Description
Break (Off)	Creates equivalent explicit rights based on the current inherited rights. Inheritance can be broken on any object.
Inherit (On)	When reactivating inheritance on an object, where a user, group or role exists on the parent object, any existing rights are replaced by the inherited permissions from the parent. When turning inheritance back on, only Inherited Allow, Inherited Deny, or None are applied to the roles, users, and groups. If the role, user, or group does NOT exist on the parent, the role, user, or group remains on the object and retains its explicit permissions. The role, user, or group is not removed or rights reset based on the parent settings.

Inheritance

Description

Break (Off)

Creates equivalent explicit rights based on the current inherited rights. Inheritance can be broken on any object.

Inherit (On)

When reactivating inheritance on an object, where a user, group or role exists on the parent object, any existing rights are replaced by the inherited permissions from the parent. When turning inheritance back on, only Inherited Allow, Inherited Deny, or None are applied to the roles, users, and groups.

If the role, user, or group does NOT exist on the parent, the role, user, or group remains on the object and retains its explicit permissions. The role, user, or group is not removed or rights reset based on the parent settings.

Setting Permissions

To create roles see K2 Management Site> Users> Roles
To set Role permissions see Add Role Security
To set object rights see Categories,Views, Forms, SmartObjects
To set rights on K2 Designer see K2 Designer
To set rights on workflow steps see Workflows - Step Authorization

Considerations

See the Before you begin topic and best practices section before you start assigning rights
Security Administrators always have View, Create, Modify, Execute, Delete and Security rights on all objects. This ensures that they can never be locked out of the system
People needing to package or deploy solutions must be a member of the K2 Package and Deployment role, must have View rights on all the objects in the package, and Modify rights on the source and destination categories. When you create a package that contains objects with explicit deny rights (View: Deny on the K2 Artifact on the source environment), Package and Deployment prevents you from creating the package and lists all the denied objects. This is because Deny takes precedence over the Package and Deployment role. See the Permissions and Common Tasks topic for more information
Deny takes precedence over all permission settings (except for Security Administrators role)
If you have no rights on views, forms, or the category in which they reside, you cannot run views and forms at runtime and you will receive an error
Anonymous forms ignore configured permissions and use default execute permissions which are Inherited Allow
If the Execute:Deny permission is set on a view, users included in the Execute:Deny permission who attempt to open the view (or a form that contains that view) will see an error like:
"Form '[FormName]' could not be found. Ensure that the form exists, that it is checked in, and that you are authorized to run the form and its views"
or
"View [ViewName] could not be found. Ensure that the view exists, that it is checked in and that you are authorized to run the view."
This error displays because you do not have the correct rights (Execute:Allow) to execute the view or the form (that contains the view) at runtime
To enable the Detailed Error Message Details option in the error message, edit the <add name="ExtendedExceptionDetail" value="false" /> to true in the SmartForms Runtime Web.config file in the following location: [Drive]:\Program Files (x86)\K2\K2 smartforms Runtime

Best practices for managing security permissions:

Plan out your security category structure before configuring permissions
Before you start configuring rights and security in K2 Management, create a plan that describes what objects are to be accessed by which roles, users, and groups. Knowing this beforehand makes it easier to configure permissions.
Configure and test the permissions and rights in a development environment first.
To avoid people in your organization from seeing and accessing objects not meant for them, configure and test your planned category security structure in a development environment. This allows you to correct the structure to ensure that the intended people have access to objects in the categories. Once you are satisfied with the configuration, you can configure your production environment to mirror the development environment.
Create test accounts in each role to test effective rights
Create test accounts for each of the main roles in your organization to test out the effective rights. Log in as the test account user and ensure that the rights have been applied correctly and it is working as expected.
Assign rights to roles and / or groups rather than individual users
Company roles, such as HR managers, are relatively static, whereas individuals may frequently join or leave the company, or change positions. To accommodate this movement of people, best practice is to assign permissions to roles or groups. When you do this, you can manage rights by adding or removing people from these roles or groups without having to revisit how permissions are currently working.
Block access by not granting permission, rather than explicitly denying rights
Deny has the highest priority when determining effective rights, and this can make it difficult to allow an exception if a person needs access to an object but they belong to a group or role that has been denied permission. If a group or role should not have access to an object, then it is best not to set permissions. This ensures that access remains blocked. However, it is easier to grant permission in the future should this be necessary.
Set permissions at category level
All securable objects must belong to a category, and then set security on the category level. By default, all objects within a category inherit permissions from the category. As the number of objects generally exceeds the number of categories, this simplifies your permissions configuration.
Use additive rights rather than breaking inheritance
The nature of your solutions and category structure determines when you need to change the assigned permissions for various objects. Breaking inheritance should be kept to a minimum. Using an inherited model and the ability to view items is the recommended way to lock down objects and keep maintenance to a minimum. The Everyone role is added by default and it is recommended that you set the Everyone Role view rights on the highest category node to None, this will inherit down to the children. You can then set the required additive rights on roles that can be inherited by the children. Note when you set the Everyone Role rights to None you will no longer see the Everyone role in the Rights UI.
Restrict view rights on forms
If a form contains a view that has Execute:Deny rights at runtime the form displays an error at runtime because you do not have rights to execute the view. If a form contains a view that has View:Deny rights, you can still run the form and execute the view on the form in runtime. If you want users to see the form but not a specific view on that form at runtime, it is recommended to add a hide a view on the form rule action on the form initialize rule. If you don’t want users to execute a form or view at runtime, it is recommended that Execute: Deny rights be configured on the views and forms to deny access to certain users and groups.