This module provides a working implementation of a role-based user permission system.
This module can be added to any Tersus application to control the access and usage of specific parts of the application by users in any desired granularity.


Introduction

Basically, a user may use a restricted part of the application if he/she is assigned a role that is associated with an appropriate permission.
More formally, a user is eligible to access specific application functionality (e.g. seeing a view or pressing a button), when the following conditions are met:

1. The model of said functionality has been assigned a permission designator P by setting its requiredPermission property to P (during modeling).
2. A role R has been assigned the permission P (using the Roles view provided by this module).
3. The user U has been assigned the role R (using the Users view provided by this module).
4. The user U has provided the required credentials (a password) when prompted to do so.

For example, the module itself employs this mechanism to limit access to the Users and Roles views to users which have been granted the View Users and View Roles permissions resepctively. (It also creates a default user with said permissions, so that the views will be accessible - see Module Implementation)

The Tersus Server has built-in security infrastructure which implements this type of authorization system based on data found in specific database tables (discussed below).

Module Implementation

The module contains 4 Database Records:
User - Stores User IDs and matching Passwords for all users of the application (mapped to the Users table in the database).
Role - Stores the Roles defined for the application (mapped to the Roles table in the database).
User_Role - Stores the assignments of Roles to User IDs (mapped to the User_Roles table in the database, a join-table implementing the many-to-many relationship between Users and Roles).
Role_Permissions - Stores the assignments of Permissions to Roles (mapped to the Role_Permissions table in the database, a join-table implementing the many-to-many relationship between Roles and Permissions).

Since the 4 database tables specified above are used by the security infrastructure built into the Tersus Server, they should not be renamed, and existing fields should not be removed or changed. However, additional fields may be added if required for specific application functionality.

The module provides 2 Views for managing the user permission system:
Users - This view is used to manage users and assign them with roles. The view is itself controlled by the user permission system - the requiredPermission property of the Users view is set to View Users - users who need access to this view, typically the system administrator, must have this permission assigned.
Roles - This view is used to manage roles and assign them with permissions. The requiredPermission property of the Roles view is set to View Roles - users who need access to this view must have this permission assigned.

The module also includes the Initialize service process. Its purpose is to bootstrap the user permission system (therefore, it is not exposed to the users).
The Initialize process is executed each time the application is started within the Tersus Server, and includes the following sub-processes:

1. Maintain Role Super with Full Permissions
   If the role Super does not exists, it is added to the Roles table.
   Regardless, it is always assigned with all permissions currently defined in the application, including the View Users and View Roles permissions (in the Roles_Permissions table).
   Note that in order to keep the role Super up-to-date, this sub-process is also included in the Init processes of the Users and Roles views. 
2. Create User Super if User Table is Empty
   If the Users table is empty, the user Super is created (User ID=Super, Password=Super). The new user Super is mapped to the role Super (in the User_Roles table).

Security Note: When deploying the application, the system administrator should create other users and delete the default Super user.

Usage Instructions

To use this module, select it from the Palette and drop it into the Root Model.
This will add a new system (with the default name Authorization), which in turn will appear as an additional perspective in the browser.

In order to view the changes to your application in the browser, you should do the following:

1. All browser windows should be closed.
2. If you application overrides the default configuration by specifiying, in the project root folder, a local Configuration.XML file, make sure to add to the <Application> element, the property authenticationMethod with the value JDBC.
3. Start the application in the Application Server. If the application is already started, it must be stopped, then restarted so that the required database updates are performed.
4. Launch the application in a browser window.
5. When prompted for a username and password, you may supply the default values (username=Super, password=Super).
6. Note the additional perspective (called Authorization, by default), now appearing.

See Also

The security infrastructure is discussed in the Check Permissions and Get All Permissions template documentation.