Customizing administration roles for Airlock

Introduction

Since Version 5.0 Airlock WAF 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

Please be aware that future versions of Airlock may break backward compatibility due to format or semantic changes and make backups of all changes made by following this tutorial. Even minor Airlock 5.0 updates could overwrite them. 

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.

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="0">
   </acl>
3. Role definition
   Start to add roles:<acl version="0">
   <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 inherits optionally permissions from an other role. Inheritance is a powerful mechanism and can be used to avoid repetitions. The inherit role "_internal_airlock_default_readonly_perms" grant an user 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 follow:
   <acl version="0">
   <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 follow: Sign in to the Airlock Configuration Center, selct 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 equals 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>
   This way, configuring permissions 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, a role can have "read" access on a page and gets "write" access by field definition. Keep in mind, that this works also 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 validators.
    
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 follow:
   <acl version="0">
   <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 WAF GUI

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

   For Airlock WAF 6.x:

   Open the following file:

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

   search for "objectDefinitionSource" and add the role:

   <property name="objectDefinitionSource">
   <security:filter-invocation-definition-source ...>
   <!-- more URL patterns here... -->
   <security:intercept-url pattern="\A/.*" access="airlock-supervisor,airlock-administrator, ..., airlock-maintenance-page-admin"/>
   </security:filter-invocation-definition-source>
   </property>
   
   If the role must be able to activate an Airlock configuration, it must be also added to the pattern "\A/configuration/ajax/invoke?.*activate.*". The example below shows how to do so:
   
   <property name="objectDefinitionSource">
   <security:filter-invocation-definition-source ...>
   <!-- more URL patterns here... -->
   <security:intercept-url pattern="\A/configuration/ajax/invoke?.*activate.*" access="airlock-supervisor,airlock-administrator,airlock-app-admin,airlock-maintenance-page-admin"/>
   </security:filter-invocation-definition-source>
   </property>

   For Airlock WAF 7.0:

   Open the following file:

   /opt/airlock/mgt-tomcat/webapps/airlock/WEB-INF/classes/applicationContext-security.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(?i)/rest/configuration/.*" access="airlock-supervisor,airlock-administrator,airlock-app-admin,airlock-maintenance-page-admin"/>
   <sec:intercept-url pattern="\A(?i)/rest/status/block/[0-9]+/reject.*" access="airlock-supervisor,airlock-administrator,airlock-app-admin,airlock-maintenance-page-admin"/>
   <sec:intercept-url pattern="\A(?i)/rest/status/backendgroup.*" access="airlock-supervisor,airlock-administrator,airlock-app-admin,airlock-maintenance-page-admin"/>
   <sec:intercept-url pattern="\A(?i)/rest/status/session.*" 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:
   service airlock-mgt-tomcat restart
9. Adding group to airlock-user-manager script
   Airlock comes with a script which 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 an user. This can be done by doing:
   
   vi /opt/airlock/base/bin/airlock-user-managerAdd the role airlock-maintenance-page-admin to the following line:
   ...
   my @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/applicationContext-security.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 Update/Hotfix those files are configured as expected.

10. Adding users
    To add a new user and assign them to a role, run the airlock-user-manager script and follow the instructions:
    airlock-user-manager