Difference between revisions of "Users and Roles"

Latest revision as of 08:17, 6 March 2023

This article explains how to set up users in the Users Workspace and assign Roles to them which determine their access to each element of an App from an individual Field on a form right up to the App itself.

The target audience is beginner to advanced developers who have read through and understood the Getting Started Guide.

See Also

• Getting Started Guide

• Watch the Users Workspace video:

Note: this video covers static roles only.

Overview

Access to Lianja Apps is based on 'users'

You assign a username and password to your users, so that they can log in to the App Center.

The users' permissions are determined by their 'roles'.

You can assign multiple roles to each user and these roles control the operations that user is allowed to carry out.

Roles can be assigned at four levels.

Roles can apply to Apps, Pages, Sections and Fields. Depending on the level, the operations controlled include Admin, Create, Read, Update and Delete.

Roles can be static or dynamic.

Static roles are specified when building an App. The developer sets the access permissions for the App and its individual Pages, Sections and Fields by associating them with one or more static roles. The actions of static roles cannot be changed after App deployment, although the users' records in the system!sysroles table can be modified to assign or remove those static roles from particular users.

Dynamic roles are read when a user authenticates and are applied to the UI at runtime. The actions of dynamic roles are stored in the system!sysperms table. This means that dynamic roles can be customized by adding, modifying or deleting the action records whenever required.

Row level Security (RLS).

Row level security allows for the filtering of rows based on an authenticated user's roles.

• Row level Security in the Users Workspace
• Example entries
• More on Row level Security

Dynamic Data Masks.

Dynamic data masks allow for the setting of masks, e.g. partial or encrypted display, at column level based on an authenticated user's roles.

Expiration Date.

When setting up users and their roles and permissions, you can specify an expiration date for the user. When a user logs in or when an http request is made a check is made for expired users and the login or request is rejected. This provides improved support for subscription based users in a SaaS environment.

Cloud Server Registrations.

From Lianja v8.0 the Lianja Cloud Server can be configured to allow users to self-register in a tenancy. See Cloud Server Registrations for details.

One-Time Passcode Two Factor Authentication

From v8.0, two factor authentication (2FA) is supported for the Lianja Cloud / Lianja Cloud Server via the sending of a one-time passcode (OTP). See Customizing the Login Page:One-Time Passcode Two Factor Authentication for details.

The Users Workspace

The Users Workspace is where you add, update and delete usernames, passwords, email addresses and permission levels for the users who will access your Apps.

This is also where you manage row level security and dynamic data masks based on user roles.

The Users Workspace has four tabs Users and Roles, Dynamic Roles and Permissions, Row level Security and Dynamic Data Masks. Each tab contains a grid of current entries, topped by a series of toolbuttons and fields to input user or role specifications.

Pro Tip:

From v8.0, where the current App has the Available roles specified in the App Settings,
those roles will appear in the role selection dialog.

Users and Roles

This is where you enter details for individual users: the username and password they will use to authenticate and the dynamic and static roles that have been assigned to them, along with optional full name and email address information.

Fields

loginapp=form2,public

Data is stored in the system!sysroles table.

Toolbuttons

When you install the Lianja App Builder, one user is already created - the 'admin' user, with the same password: 'admin'. You don't need to use these login details when you start the App Builder - you will be logged in automatically - but, you do need them to log into the Lianja App Center or when you log out of the App Builder and want to login again as 'admin'.

To change the admin password, click on the grid row to select the admin user and enter the new password in the Password field. You can see the password as you type it, but only its cryptographic key will be displayed in the Users grid and stored in the sysroles system table. Click Update to save your change.

To add a new user, enter the Domain or '*' for public and then the Name, Username and Password and optional Email address. Leaving the Roles field blank, or entering a '*' gives the user all roles. Click Add to create the new user.

Users can be deleted by selecting them in the grid and clicking Delete. The Clear button is used to deselect a selected user and the Refresh button to reread the sysroles system table and refresh the display.

In the Users Workspace screenshot above, I have added a few users - Harry, who works in Human Resources and has the hr and dynhr roles, Sally, who is a Sales Representative and has the sales and dynsales roles and Ricky who looks after Reception and has the dynreception role. Mandy, a Manager, is in the process of being added in the screenshot above is being given the dynmanager role. For the purposes of this example, 'hr' and 'sales' are static roles and 'dynhr', 'dynsales', 'dynmanager' and 'dynreception' are dynamic roles, but you can choose your own naming conventions.

Dynamic Roles and Permissions

This is where you enter action details for dynamic roles: the name of the role, the App(s) and UI control it applies to and the permissions it assigns.

Note: The permissions of static roles are defined within Apps. This is explained in Using Static Roles below.

Fields

Data is stored in the system!sysperms table.

Toolbuttons

To add a new role, enter the name of the role, the App(s) and UI control it applies to and check the boxes for the permissions it assigns. Click Add to create the new role.

To update a role, click on its grid row to select it, make your changes, then click Update to save the changes.

Roles can be deleted by selecting them in the grid and clicking Delete. The Clear button is used to deselect a selected role and the Refresh button to reread the sysperms system table and refresh the display.

In the screenshot above, I have added action entries for the dynhr, dynsales and dynmanager dynamic roles and their corresponding !dynhr, !dynsales and !dynmanager dynamic roles. There is also an entry for the dynreception dynamic role, which has no matching !dynreception role. To see the effect of these role definitions, see Using Dynamic Roles below.

Row level Security (RLS)

This is where you enter details for row level security: row filters that will be applied to a specified table in a specified database for one or more roles.

Pro Tip:

From v8.0, where the current App has the Available roles specified in the App Settings,
those roles will appear in the role selection dialog.

Fields

Data is stored in the system!sysrowfilters table.

Toolbuttons

In the screenshot above, I have added two row filters. To see the effect of these, see Using Row level Security below.

Dynamic Data Masks

This is where you enter details for dynamic data masks: data masks that will be applied to specified columns in a specified database table for one or more roles.

Fields

Data is stored in the system!sysdatamasks table.

Toolbuttons

Using Static Roles

Pro Tip

From v5.3 you can use the special lianjadev static role for testing.
The default admin Lianja App Builder user does not have the lianjadev static role,
so you can switch to Desktop App View and see the effect in your App when a user does not have role permissions.

As we have seen, static roles are assigned to specific users in the Users Workspace, but their permissions are defined within individual Apps. With the Users and Roles information complete, I can now set up which parts - if any - of my App can be accessed by Harry, Sally, Ricky and Mandy (and any other users I add later) based on the hr and sales static roles.

Page Roles

I've created an App called roledemo and added three simple Pages: pCustomers for Customers, pHR for HR and pOrders for Orders.

I start by setting different Read roles to restrict who can see each Page.

Pro Tip:

From v8.0, specify the roles you need for that App in the Available roles in the App Settings.
These roles will then appear in the role selection dialog in the Page Builder Assistant.

Both sales and hr will be able to see the pCustomers Page.

Here's where to specify the Read roles in the Page Builder Assistant (from v8.0):

Only hr will be able to see the pHR Page.

Here using the Attributes tab in the App Inspector:

Only sales will be able to see the pOrders Page.

Here using the Attributes dialog (App Inspector closed), opened by clicking the 'cog' icon in the Headerbar or double-clicking in the Page header:

As well as the Read roles, you can also restrict whether a user can Create, Update or Delete data on the whole Page. In each case enter the name of the role, and if you want to use multiple roles, separate them with a comma.

Publish App

Before testing the Page roles in the Lianja App Center on my development machine, I need to 'Publish' the roledemo App and 'Deploy' the users tables and the roledemo App.

To Publish the App, I check the Published checkbox in the App Settings: click on the Settings button in the Modebar or select the 'App' tab in the App Inspector Attributes tab.

The roledemo App will now have a tile in the Home Workspace in the Lianja App Builder.

At this point, you can test the Page roles in the Lianja App Builder by logging out in the Home Workspace and logging in as the users specified below.

Alternatively, you can Deploy the roledemo App and the users tables and test in the Lianja App Center.

Deploy App and Users Tables

To make a Published App available in the Lianja App Center, it has to be Deployed. The same is true for any users and roles you create or modify.

Select the Deploy Workspace from the Modebar, or select Setup from the Quick Deploy dialog.

Check the box next to the system database:

Note: these deployment screenshots are from the Lianja App Builder installed on Windows drive E:.

Check the box next to your App(s), Scripts or other databases you want to deploy and then click 'Preview changes' followed by 'Commit changes' in the Headerbar.

Quick Deploy

You can also deploy from the Pages Workspace using Quick Deploy.

Using the Quick Deploy dialog, you can select the files you want to deploy in the Deploy Workspace, then just click Preview and Commit as often as required to preview and commit those selected files.

Quick Deploy can also be used in the Users Workspace, where it automatically selects the system database containing the users and roles tables.

Click Preview to preview the selected deployment files and Commit to deploy them.

Testing Page Roles

Pages available to Sally

Login as Sally from Sales.

With the sales role, Sally can see the Customers and Orders Pages, but not the HR Page.

Pages available to Harry

Login as Harry from HR.

With the hr role, Harry can see the Customers and HR Pages, but not the Orders Page.

Section Roles

Back to the Customers Page in the App Builder as admin. The Page is, as I said earlier, only one of the levels where permission roles can be set. We can refine them through Sections right down to Fields.

In the Attributes for the Customers Section, go to Permissions and Roles.

We're only going to allow users with the sales role to delete customers.

If you have already set the Available roles in the App Settings, you can use the role selection dialog in the Page Builder Assistant (from v8.0):

Field Roles

Then in the Attributes for the Customer ID Field go to Permissions and Roles.

We'll protect this important field and say that only users with the sales role will be able to update it.

If you have already set the Available roles in the App Settings, you can use the role selection dialog in the Page Builder Assistant (from v8.0):

Save the App again - deploy if you want to test in the Lianja App Center - then Login as Harry from HR. Remember, Harry doesn't have the sales role.

Harry Section Roles

In the Customers Page, try clicking on the Delete button in the Actionbar.

You will see a message displayed explaining why the record cannot be deleted.

Harry Field Roles

And if you click Edit in the Actionbar, the Customer ID field cannot be updated:

App Roles

So, we've seen Page, Section and Field level roles - that just leaves App Level roles.

In the App Settings in the Modebar go to Permissions and Roles. Admin roles restrict who can modify or delete the App itself and apply to Developers. We also have the familiar Create, Update and Delete roles - this time applying to data records across the whole App.

If I assign any Read roles, I can hide the entire App from any user who doesn't have that role. Let's limit this whole App to those with the sales or hr roles:

Now, if you save the App - deploy if you want to test in the Lianja App Center - and Login as Ricky from Reception, who does not have the sales or hr role, the roledemo App tile is not displayed.

Available roles

This App setting can be used to specify a comma separated list of roles that are available for the App.

From v8.0 this list is used to populate a popup graphical picklist in the Users and Roles workspace and in the Page Builder Assistant.

Exclusion Roles

You can also specify roles to be prevented from carrying out the operation.

Roles to be excluded should be prefixed with a '~'. Here the App Read roles is set to ~dynreception. Any user with the dynreception role will not have Read access to the App.

As before, if you Login as Ricky from Reception, who has the dynreception role, the roledemo App tile is not displayed.

Using Dynamic Roles

Here's a version of the roledemo App using dynamic roles. It has the three simple Pages: the Customers Page, called pCustomers; the Hr Page, called pHR and the Orders Page, called pOrders.

The pCustomers Page has three sections: sCustomers, sOrders and sOrderDetails. The Customer ID field in the sCustomers Section is called fCustomerID.

As we have seen, these names are used in the UIcontrol field for dynamic roles in the same way as referencing an object using Lianja.getElementByID() in the Lianja Object Model.

When a user logs in and opens an App, the system!sysperms and system!sysroles tables are read to see if there are any dynamic roles which specify that App and are assigned to that user. If there are, those roles are applied. If not, no additional permission restrictions are applied. Any static role restrictions set in that App will still be in force.

In the Dynamic Roles and Permissions all the roles I have currently defined apply to the roledemo App. The dynreception role applies to all Apps (App = *) and the others specify the roledemo App. Remember you can make a role apply to multiple named Apps by specifying a comma-separated list in the App field.

So let's look at the effect of each role definition in more detail. Please note that dynamic roles are not active in the Lianja App Builder. Publish your App and deploy your App and the users and roles files to test in the Lianja App Center.

Singleton Dynamic Roles

The dynreception dynamic role is a singleton dynamic role - it has no matching !dynreception role. It has the following definition:

It applies to all UIcontrols (*) within all Apps (*) and gives the user only Read permission. So, Ricky, who has the dynreception role will only have Read permission in all the Apps he has access to, with no permissions to create, update or delete any data. The dynreception role has no effect on any user without the role.

Dynamic Role Pairs

The other dynamic roles defined above are dynamic role pairs. That is, for each main role, there is a matching role with a ! prefix. In this case, the ! prefixed role will be applied to any user who does not have the main role.

For example, here is the dynhr role:

and the matching !dynhr role:

They both apply to just the pHR Page in the roledemo App. Anyone who has the dynhr role, currently just Harry, will have full Create, Read, Update and Delete permissions for the pHR Page. All users without the dynhr role will have the !dynhr role applied when they open the roledemo App and will not even be able to see (Read) the pHR Page. This role and the others that follow here have no effect on any App other than the roledemo App.

Here is the dynsales role, which has two entries:

and the matching !dynsales role:

Sally, who has the dynsales role, will be given full permissions for the pOrders Page; no other users will be able to see (Read) the Page. Sally also has additional permissions for the fCustomerid Field (Customer ID) in the sCustomers Section on the pCustomers Page compared to other users: Sally can Create, Read, Update and Delete; all other users can only Read the data.

And here is the dynmanager role, which again has two entries:

and its matching !dynmanager role:

Only users with the dynmanager role, such as Mandy, will be able to see the sOrders and sOrderDetails Sections on the pCustomers Page. The dynmanager role gives full permissions, but all other users will have the !dynmanager role applied and will have no access permissions to these Sections.

Using Row level Security

Here, I have added two row filters for the customers table in the southwind database.

Users with the 'salesuk' role will only see rows where the country column is 'UK'.

Users with the 'salesusa' role will only see rows where the country column is 'USA'.

Users without these roles will not have row filters applied.

The user 'Sandy' has the 'salesuk' role and the user 'Sally' has the 'salesusa' role.

Signed in as Sandy, only UK customers will be shown.

Signed in as Sally, only USA customers will be shown.

See also these associated language elements:

• SET ROWFILTER
• USERROWFILTER()
• $rowfilter OData argument

Customizing Deployed Users and Roles

User records and dynamic roles are stored in the users tables in the system database, so new records can be added or existing records modified or deleted through batch operations or by building an administration App accessible to privileged users.

As mentioned above, this will not allow the behavior of static roles to be changed as these are built into the individual App, but static roles can still be assigned to or removed from particular user records.

Notes on Client Support

Summary

Use the Users Workspace to add your users and set their Roles, controlling their permissions at App, Page, Section and Field level. Then you can design and build Apps that can be used by different departments or different groups with different permission levels while correctly protecting the data and all without coding.