Difference between revisions of "Users and Roles"

From Lianjapedia
Jump to: navigation, search
(Notes on Client Support)
(Notes on Client Support)
Line 791: Line 791:
 
!width="80%"|Notes
 
!width="80%"|Notes
 
|-
 
|-
|valign="top"|Static Roles||Supported on the Desktop and Web and PhoneGap Mobile clients.
+
|valign="top"|Static Roles||Supported on the Desktop, Web and PhoneGap Mobile clients.
 
|-
 
|-
 
|valign="top"|Dynamic Roles||Supported on the Desktop client only.
 
|valign="top"|Dynamic Roles||Supported on the Desktop client only.

Revision as of 23:53, 14 April 2018

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

  • 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).

Introduced in Lianja v3.4, row level security allows for the filtering of rows based on an authenticated user's roles.

Dynamic Data Masks.

Introduced in Lianja v3.4, 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.

Introduced in Lianja v4.0, when setting up users and their roles and permissions, you can now 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.

The Users Workspace

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.

The Users Workspace has two grids: one for Users and Roles, the other for Dynamic Roles and Permissions. Each is topped by a series of toolbuttons and fields to input user or role specifications.

See below for the redesigned Users Workspace from Lianja v3.4.


Users Workspace


Lianja v3.4

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.

See above for the layout of the Users Workspace prior to Lianja v3.4.

Users Workspace



Lianja v4.0

From Lianja v4.0, each user can optionally have an expiration date set: Expiry.

Once the user's expiration date has passed, their login will be rejected as invalid.



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

Field Description
Domain Domain or tenancy for the user. The public tenancy was indicated by '*' in earlier versions of Lianja. This should now be specified as 'public'.
Name Full name of the user.
Username Login name of the user, case-sensitive.
Password Password for the user, case-sensitive. This is encrypted as an MD5 cryptographic key when saved.
Expires Expiration date for the user. Login or http request is rejected if a user's expiration date has passed. From v4.0.
Email User's email address.
Roles Comma-separated list of roles for the user. Empty or '*' means all.

Data is stored in the system!sysroles table.

Toolbuttons

Button Description
Add After filling in the fields, click the Add button to create the new user.
Update After selecting a user and changing the fields, click the Update button to commit the changes.
Delete After selecting a user, click the Delete button to delete the selected user.
Clear Click the Clear button to clear the fields, so no user is selected.
Refresh Click the Refresh button to reread the sysroles system table and refresh the Users and Roles display.

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.

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

Fields

Field Description
Role Unique name for the role. Roles prefixed with ! are applied to all users who do not have the equivalent non-prefixed role.
App Name of App to which the role is applied. Multiple roles can be specified by a comma-separated list. '*' means all Apps.
UIcontrol Name of the UIcontrol to which the roles is applied. This is the same as the object reference used by Lianja.getElementByID() in the Lianja Object Model
Create Check to allow the role Create permission for the UIcontrol.
Read Check to allow the role Read permission for the UIcontrol.
Update Check to allow the role Update permission for the UIcontrol.
Delete Check to allow the role Delete permission for the UIcontrol.

Data is stored in the system!sysperms table.

Toolbuttons

Button Description
Add After filling in the fields, click the Add button to create the new role.
Update After selecting a role and changing the fields, click the Update button to commit the changes.
Delete After selecting a role, click the Delete button to delete the selected role.
Clear Click the Clear button to clear the fields, so no role is selected.
Refresh Click the Refresh button to reread the sysperms system table and refresh the Dynamic Roles and Permissions display.

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 Users Workspace 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.

Fields

Field Description
Domain Domain or tenancy for the user. The public tenancy was indicated by '*' in earlier versions of Lianja. This should now be specified as 'public'.
Database Name of the database.
Table Name of the table.
Role Comma-separated list of roles.
Row Filter The logical condition to be applied as a filter.

Data is stored in the system!sysrowfilters table.

Toolbuttons

Button Description
Add After filling in the fields, click the Add button to create the new row filter.
Update After selecting a row filter and changing the fields, click the Update button to commit the changes.
Delete After selecting a row filter, click the Delete button to delete the selected row filter.
Clear Click the Clear button to clear the fields, so no row filter is selected.
Refresh Click the Refresh button to reread the sysrowfilters system table and refresh the Row level Security display.

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

Field Description
Domain Domain or tenancy for the user. The public tenancy was indicated by '*' in earlier versions of Lianja. This should now be specified as 'public'.
Database Name of the database.
Table Name of the table.
Column Name of the column.
Role Comma-separated list of roles.
Mask The mask to be applied: default, partial, email or encrypted.

Data is stored in the system!sysdatamasks table.

Toolbuttons

Button Description
Add After filling in the fields, click the Add button to create the new mask definition.
Update After selecting a mask definition and changing the fields, click the Update button to commit the changes.
Delete After selecting a mask definition, click the Delete button to delete the selected mask definition.
Clear Click the Clear button to clear the fields, so no mask definition is selected.
Refresh Click the Refresh button to reread the sysdatamasks system table and refresh the Dynamic Data Masks display.

Using Static Roles

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

Roledemo App


I've created an App called roledemo and added three simple Pages: Customers, Hr and Orders.

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


Customers Page Roles


If you have the App Inspector open, select each Page in turn, then in the Attributes tab in the App Inspector, select 'Permissions and Roles' from the pulldown and fill in the fields.


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


HR Page Roles


If you do not have the App Inspector open, double-click on each Page header in turn (or click on the cog) to access the Page Attributes, select 'Permissions and Roles' from the pulldown and fill in the fields.


Only hr will be able to see the HR Page.


Orders Page Roles


Only sales will be able to see the Orders Page.


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.

Publish roledemo App


To Publish the App, I check the Published checkbox in the App Settings dialog, which is activated by the Settings button in the Modebar.


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 system database


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


Check the box next to the system database.


Select the App and any other files and Deploy


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

Quick Deploy


From Lianja v3.0, you no longer need to close your App before deploying.

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 in Users Workspace


From Lianja v3.2, when you click the Quick Deploy toolbutton in the Users Workspace 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.

Section Roles


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.


Field Roles

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.


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.

App 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.

Exclusion Roles

Prior to Lianja v3.0, the static roles could only be used to specify users who could carry out a particular operation. Now, you can also specify roles to be prevented from carrying out the operation.

Roles to be excluded should be prefixed with a '~'.

App Roles excluding a role


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

Dynroledemo App


I've created a new App called dynroledemo, which again has 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 dynroledemo App. The dynreception role applies to all Apps (App = *) and the others specify the dynroledemo 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:

Role App UIcontrol Create Read Update Delete
dynreception * * False True False False

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:

Role App UIcontrol Create Read Update Delete
dynhr dynroledemo pHR True True True True

and the matching !dynhr role:

Role App UIcontrol Create Read Update Delete
!dynhr dynroledemo pHR False False False False

They both apply to just the pHR Page in the dynroledemo 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 dynroledemo 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 dynroledemo App.

Here is the dynsales role, which has two entries:

Role App UIcontrol Create Read Update Delete
dynsales dynroledemo pOrders True True True True
dynsales dynroledemo pCustomers.sCustomers.fCustomerID True True True True

and the matching !dynsales role:

Role App UIcontrol Create Read Update Delete
!dynsales dynroledemo pOrders False False False False
!dynsales dynroledemo pCustomers.sCustomers.fCustomerID False True False False

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:

Role App UIcontrol Create Read Update Delete
dynmanager dynroledemo pCustomers.sOrders True True True True
dynmanager dynroledemo pCustomers.sOrderDetails True True True True

and its matching !dynmanager role:

Role App UIcontrol Create Read Update Delete
!dynmanager dynroledemo pCustomers.sOrders False False False False
!dynmanager dynroledemo pCustomers.sOrderDetails False False False False

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

Row level Security



Here, I have added two row filters for the customers table in my docdb (copy of the southwind sample) 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.


Users and Roles



I have created a new user 'Sandy' with the 'salesuk' role and updated Sally's roles to include 'salesusa'.

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:

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

Feature Notes
Static Roles Supported on the Desktop, Web and PhoneGap Mobile clients.
Dynamic Roles Supported on the Desktop client only.
Row level Security Supported on Desktop, Web and PhoneGap Mobile clients.

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.