This article continues our series on best practices and tips for App Developers and Administrators. The previous articles in this series can be found here:
This is a general reference article, for security questions specific to your environment get in touch with your Onit representative or ask a question on our forum.
Custom Roles
Custom roles are an easy way of granting permissions to users on a Record. Below is a reference table for all roles in the Onit system and an explanation of their permissions. Creating a custom role allows App Builders to grant the exact permissions users should have on a Record.
Be aware: The "Create Transaction" checkbox has a somewhat misleading label. This box covers a particular use case: if you have an app where the Authentication Level is set to Restricted (so regular users can't launch it), and you want a user group whose users are able to launch the app, but you don't want them to see every transaction in the app, you can create a custom rule to use in the user group with this box checked.
Note that it is not required to check this box in order to allow users with this role to launch an ordinary app.
| Role Name |
Role Permissions |
|---|---|
| Administrator: A participant that needs admin privileges on the Record. |
|
| Approver: A participant that needs to take action on the Record. |
|
| Requester: The participant requesting/submitting the Record. |
|
| Read Only Approver: A participant that needs to take action on the Record, such as approve or reject; but who does not need to edit the details, change the Phase or edit or remove a participant. |
|
| Read Only Requester: The participant requesting/submitting the Record. He or she can access the Record and view its details; but cannot edit details, change the phase, add participants, see comments make, make comments, or view the history. |
|
| Read Only Reviewer: A participant that will need to review the Record, but does not need to approve, reject, or change the Phase. |
|
| Reviewer: A participant that will need to review the Record, but does not need to approve or reject. |
|
| Requester (Limited): The participant requesting/submitting the Record. However, he or she will not have access to the transaction after submission. This user can still receive email notifications but will not be able to view the transaction details in the application. Note that the Requester will still be added to the corporate user list even though they never access the transaction. |
|
| Custom: An App builder can configure a custom role to use in their App. The custom role can have any of the previously discussed permissions (i.e., admin rights, edit rights, read-only rights, etc.). |
Inherited Roles (Security Chains)
For instructions on how to create an inherited role, see the Crash Course on Security Tutorial.
Inherited roles allow for an organic evolution of user access based on related Records in a "controller" App.
For example, Acme Corp. creates a new Record named Coyote Injury Waiver. Using the related Acme-Legal-Teams "controller" App Onit can grant appropriate permission without manually assigning permission to users.
The related Acme-Legal-Teams "controller" App works to determine which users should have access to each Record through inherited roles.
When the Coyote Injury Waiver Record is created, a Business Rule relates it to the Coyote Legal Team Record in the Acme-Legal-Teams App. Once the Record is related all users in the Coyote Legal Team Record are granted access to the new Record.
Things to watch out for: Inherited roles start to have a hard time around 50,000+ Records, so keep an eye on how large your environment becomes.
How do User Groups relate to Inherited Roles?
Imagine two Apps, App 1 and App 2.
App 2 has a relation to App 1 with an inherited role. So if John is a participant on a Record in App 1, he also gets to see any related Records in App 2.
So far, so basic. Now imagine that App 1 has a user group. John isn't a participant on the App 1 Record, he sees it because of the user group. Does John get permission to see the related App 2 Record, via the inherited role?
Yes. Anyone who has permission to view the App 1 Record gets to partake of the inheritance also.
Known Private User Group Bug: For users in multiple Private User Groups we are aware of a bug which could prevent access to private Records.
Consider a user who belongs to Private Groups A and B. Group A does not have access to private Records, but B does. If Private Group A was created first, the user would not have access to any private Records. If Group B was created first, the user would have appropriate access to private Records.
User Groups vs. Group Preference vs. Security Groups
We often see confusion between the items mentioned below, often used interchangeably due to the overlapping terminology around them. In order to clear up any confusion, here is a definition and use of each:
- User Group - At the /admin level, User Groups provide role-based access control (RBAC) to records. Users are added to User Groups, which are then associated to Apps under the Security section in the App’s Advanced Designer page. User Groups grant users access to all Records in an App, provided that the Records are not marked as private. In the event that there are Records marked as private, they will only be accessible to participants of that Record, and to users associated to a User Group that has Private Access. Private Access User Groups are created the same way as regular User Groups
- Group Preference - a Group Preference object controls what users see in the landing page (called a Suite) when they log into Onit. It spells out the main Suite and Dashboard that they see, as well as defining the sidebar items and plus button items that they have access to in the Suite. Though this is not considered security, it provides a small bit of view-layer security, in that users who cannot see certain Apps in the sidebar, or cannot add records through the plus button items, do not know they exist.
Warning - users can gain access to other Suites if they are given the link to them. This is why Group Preferences is not directly considered security
- Security Groups - This is an App that manages Record access through the use of Inherited Role chaining. Security Groups are set up usually based on the taxonomy of Records in the system (for example, the area of law and matter type of Matter Records), and users are added as participants on these Security Group records. Because they inherit access to the Matter Records these Security Groups are linked to, this provides a finer-grained control of Record access than User Groups.
Limit Users to a Single User Group
To ensure maximum effectiveness and legibility in your build user's should be limited to one User Group. Stacking User Group permissions can make it hard to debug security issues in your environment. Think first of how an existing User Group could be modify instead of creating and assigning new groups.
Tab Level Security
Tab level security is an effective and inexpensive way of preventing users from seeing tabs based on their Role. When designing an App simply assign a Role to a specific Tab within the App Builder and only that Role will be able to view the Tab. The tab will not show in the DOM of users with incorrect roles.
Remember, a Field whose Show on Dashboard property is selected will still be viewable by anyone who has access to the Record on the dashboard.
Tab Level Security and Hidden Conditions
Let's suppose you have two Fields, field_a and field_b. field_b has a Hidden Condition that relies on a value in field_a.
On the Launch screen, both Fields are displayed together, and when the correct value is in field_a, field_b appears.
However, on the View screen, field_a is on a Tab that some users do not have access to. Even though the value in field_a that would make field_b appear exists, those users who do not have access to that Tab can now no longer see field_b, as though field_a did not exist.
This is due to Tab-level security, the user does not have access to the information on the Tab, the hidden condition will now no longer evaluate properly, even though it worked on the Launch screen.
If you ever come across a case where your hidden condition works on one screen but not the other, this would be a good troubleshooting point to start at. The general fix is to move field_a to a Tab that all users have access to.
Think About Security Early and Often
Before starting your project spend time thinking about the security of your environment. There are some security requirements possible in other platforms that are not possible in Onit, for example read-only security.
Often security will fall by the way side and a very brittle ad-hoc security system will develop over time. For example, Company A decides that simply restricting Record access to participants will be enough security to keep their Records safe. However, when an employee leaves Company A they now have a participant who should no longer have access to sensitive Records. The old user will need to be manually removed from hundreds of Records and replaced with another user.
Counteract this by planning your security strategy beforehand. A good place to start is our Crash Course on Security tutorial.
Test with Real Size Data Loads
Always test your environment's security with real size data loads. A security system could work perfectly with only a few Records, but might have trouble with thousands of Records and users.
Work with your Onit representative to simulate a large number of Records to test with.