Customizing administration roles for Airlock Gateway 7.1 to 8.2x

Introduction

Airlock Gateway comes with a default set of administration roles. This article explains how to add additional roles with different permissions.

How to add a custom role

This tutorial is not applicable for Airlock Gateway 8.3 and higher. With 8.3 we have revised the preconfigured administrative roles according to the needs reported by our customers and removed the option to create custom administrator roles.

Custom roles for access control can be added by editing /opt/airlock/custom-settings/mgt-tomcat/acl.xml. After a new installation, the xml configuration file (acl.xml) does not exist. So, create this file and set the permission properly.

To add a new user and assign them to a role:

airlock-user-manager

# For Airlock Gateway 7.2 or later use:
airlock-user-manager-tool

1. Setuptouch /opt/airlock/custom-settings/mgt-tomcat/acl.xml
   chown fown:alec /opt/airlock/custom-settings/mgt-tomcat/acl.xml
   chmod 040 /opt/airlock/custom-settings/mgt-tomcat/acl.xml
2. Empty XML configuration
   Download the following acl.xml as an example with the airlock-maintenance-page-admin role definition.Open the XML file in an editor and make sure that the XML is well-formed:
   <acl Version="1">
   </acl>
3. Role definition
   Start to add roles:<acl Version="1">
   <role id="airlock-maintenance-page-admin" permission="read" inheritsFrom="_internal_airlock_default_readonly_perms">
   </role>
   </acl> Each role needs a unique identifier, in this example "airlock-maintenance-page-admin", in order to refer to that role later. A default permission is also configured for each role, in this case "read", and optionally permissions from an other role are inherited. Inheritance is a powerful mechanism and can be used to avoid repetitions. The inherited role "_internal_airlock_default_readonly_perms" grants a user the right to navigate through the menu, watch the error pages preview and some more pages in the Airlock Configuration Center. Inheritance is not limited to predefined roles which are delivered with a new installation, it is also possible to inherit from custom roles.
4. Page permissions
   Permissions for a role on pages are configured as follows:
   <acl Version="1">
   <role id="airlock-maintenance-page-admin" permission="read" inheritsFrom="_internal_airlock_default_readonly_perms">
   <pages>
   <page id="virtualHost" permission="read">
   <!-- see step 5 below -->
   </page>
   </pages>
   </role>
   </acl>The configuration above allows users with the role airlock-maintenance-page-admin to access the page "virtualHost" with read permissions. The IDs of the page can be inferred as follows: Sign in to the Airlock Configuration Center, select the "Reverse Proxy" menu, edit a virtual host and click afterwards the submit button (clicking the submit button is necessary to get the correct URL. To configure the permissions for menu entries, the menu entry has to be clicked twice). For example the URL for the page "Virtual Host" is:
   https://<airlock_host>/airlock/configuration/virtualHost.jsf
   The page id in the acl.xml is equal to the pagename in the URL without the extension. In this case the page id is "virtualHost".
5. Field permissions
   In step 4 (see above) the role "airlock-maintenance-page-admin" has been granted with "read" permissions on the page "virtualHost". With the configuration below it is possible to grant this role with "write" permissions just on a few fields:
   <page id="virtualHost" permission="read">
   <field id="showMaintenancePageCheckboxLink" permission="execute"/>
   <field id="showMaintenancePage" permission="write"/>
   <field id="submitVirtualHost" permission="execute"/>
   </page>
   By allowing permissions configuration on page level and on field level, it is possible to define access very granular. Important to know is, that the most specific permission wins. This means that a role can have "read" access on a page and gets "write" access by field definition. Keep in mind that this also works the other way around. So a role can have "write" access on a page and is limited with "read" access on some fields.
   
   The field identifiers can be inferred from the HTML source code. It makes definitively sense to grant the role with "execute" permission on the submit button, as done in the example above. This way the admin can validate the changed configuration by clicking on the submit button which triggers the configuration validation.
    
6. Global field permissions
   Some fields are not linked to a specific page, they are global. One example is the navigation menu or the "Activate" button. Permissions for those global fields are configured as follows:
   <acl Version="1">
   <role id="airlock-maintenance-page-admin" permission="read" inheritsFrom="_internal_airlock_default_readonly_perms">
   <pages>
   <!-- see steps before -->
   </pages>
   <globalFields>
   <field id="activationButtonLink" permission="execute"/>
   <field id="activationComment" permission="write"/>
   <field id="localNode" permission="execute" />
   <field id="localAndFailoverNode" permission="execute" />
   <field id="activateSubmit" permission="execute"/>
   </globalFields>
   </role>
   </acl>To determine the IDs of the fields/links, look into the HTML source code.

7. Adding role to Airlock Gateway GUI

   After specifying the new roles in the file acl.xml, a small configuration change is necessary such that the Airlock Gateway Configuration Center recognizes those roles.

   Open the following file:

   /opt/airlock/mgt-tomcat/webapps/airlock/WEB-INF/classes/security-context.xml

   search for "<sec:http pattern="/.*"" and add the role to the desired URLs:

   <sec:http pattern="/.*"...>
   <!-- Other settings here. Do not change them... -->
   <sec:intercept-url pattern="\A(?i)/configuration/addonmodules/.*" access="airlock-supervisor,airlock-administrator,airlock-maintenance-page-admin"/>
   <sec:intercept-url pattern="\A(?i)/configuration/ajax/invoke?.*activate.*" access="airlock-supervisor,airlock-administrator,airlock-app-admin,airlock-maintenance-page-admin"/>
   <sec:intercept-url pattern="\A/.*" access="airlock-supervisor,airlock-administrator,airlock-auditor,airlock-app-admin,airlock-maintenance-page-admin"/>
   <!-- Other settings here. Do not change them... -->
   </sec:http>  

8. Restart GUI
   After those changes the Airlock Configuration Center must be restarted to reload the new configuration:
   systemctl restart airlock-mgt-tomcat
9. Adding group to airlock-user-manager script
   Airlock Gateway comes with a script that allows easily to add users and set the appropriate role for them. The newly configured role must be added to this script to be able to assign the role to a user. This can be done by doing:
   
   Before Airlock Gateway 7.2:
   vi /opt/airlock/base/bin/airlock-user-manager
   
   # edit to following line
   ...
   my @ROLES = ("airlock-supervisor","airlock-administrator","airlock-auditor","airlock-app-admin", ..., "airlock-maintenance-page-admin");
   ... For Airlock Gateway 7.2 or later 
   vi /opt/airlock/base/bin/airlock-user-manager-tool
   
   # edit the following line
   ...
   VALID_ROLES = ["airlock-supervisor", "airlock-administrator", "airlock-auditor", "airlock-app-admin", "airlock-maintenance-page-admin"]
   ...

   Note: The changes in the scripts /opt/airlock/mgt-tomcat/webapps/airlock/WEB-INF/classes/security-context.xml and /opt/airlock/base/bin/airlock-user-manager are NOT update resistent. Make sure to backup those files and ensure that after installing a new Airlock Gateway Update/Hotfix those files are configured as expected.

10. Adding users