Custom security rules

What are custom security rules?

Custom security rules give you more control over the security of your app than the standard configuration offers. Custom conditions can be written using Javascript. 
Users should consider using custom security rules in the following cases:

1. You need IP restrictions 
2. You want to restrict pages based on the logged-in user data for e.g. only admins can access certain pages. 
3. You want to target specific devices for e.g a web app or a mobile app

Why use custom security rules?

Custom rules can be used in conjunction with regular security rules to add an additional security layer on top of any existing security rules 

Get Started

To implement custom security rules to your app you should:

1. Open the settings
2. Write your rules
3. Test your rules

Step 1 – Open the settings

1. Inside the app you wish to add security rules for, select the app name in the top left
2. Click on the app security tab
3. Select add new rule and choose write my own condition
   

Step 2 – Write your rules

See the how to write custom security rules article.

1. Extreme care has to be taken when writing your custom security rules. If you are writing a rule you need to think about all possible conditions of access otherwise you might be exposing a page to the wrong person or the public.
2. If you want to write lots of “If” statements then the best method is to set a boolean flag to true/false and determine at the end whether the user should be taken to another page or allowed to access the page.
3. As an example, see below a rule from our ROMS template. It’s set up to:
   1. Only users whose ‘User role’ equals to Admin can access pages that start with “Admin”. 
   2. Same with the “Office Manager” user role. 
   3. If you are neither, then you are taken to the menu screen. 
   4. Notice how the rule sets an error flag as it goes down the page and at the end, it determines if the user is allowed to access the page.
   5. At the end, there is an override where if you are Admin then you can see any page.

var menuScreen = 123456;
var hasSession = session && session.entries && session.entries.dataSource;
var isAdmin = hasSession && session.entries.dataSource.data['User Role'] === 'Admin';
var isAdminPage = page.title.indexOf('Admin') === 0;
var error = false;
var isOm = hasSession && session.entries.dataSource.data['User Role'] === 'Office Manager';
var isOmPage = page.title.indexOf('OM') === 0;

if (isOm && isAdminPage){
    error = true;
}

if (isOm && isOmPage){
    error = false;
}

if ((!isAdmin && !isOm) && (isOmPage || isAdmin)){
    error = true;
}

if (isAdminPage && !isAdmin) {
  error = true;
}

if (isAdmin) {
  error = false;
}

if (error && page.id !== menuScreen) {
  navigate = { action: 'screen', page: menuScreen, transition: 'slide.left' };
}

Step 3 – Test your rules

1. Inside your app, switch to preview mode and ensure enable security is selected
   
   
2. Test every scenario of your security rule 
3. In the example rule above, these scenarios would all have to be tested: 
   1. Admins can access admin screens 
   2. Office managers cannot access admin screens 
   3. Office managers can access OM screens 
   4. A user which is neither an office manager or an admin cannot access the screens and is redirected to the menu