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 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.
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.
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 |
Views | View Modify Execute Delete Security |
SmartObjects | View Modify Delete Security |
Categories |
View
|
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
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.
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. |
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
The Security Audit SmartObject allows a member of the Security Administrators role to execute the SmartObject and generate an audit log of all authorization framework security changes in your K2 environment. For more information, see the Security Audit SmartObject topic.
- 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 runtimeTo 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 - The security audit SmartObject only stores security changes set from the authorization framework.
- 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.