You are here

Customizing administration roles for Airlock WAF 7.1 or later

Affects product: 
Airlock WAF
Affects version(s): 
7.1.x or higher


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 WAF may break backward compatibility due to format or semantic changes and make backups of all changes made by following this tutorial. Even minor Airlock WAF 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.

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


# For Airlock WAF 7.2 or later use:

  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">
  3. Role definition
    Start to add roles:<acl Version="1">
    <role id="airlock-maintenance-page-admin" permission="read" inheritsFrom="_internal_airlock_default_readonly_perms">
    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">
    <page id="virtualHost" permission="read">
    <!-- see step 5 below -->
    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:
    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"/>

    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">
    <!-- see steps before -->
    <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"/>
    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 change is necessary such that the Airlock WAF Configuration Center recognizes those roles.

    Open the following file:


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

  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 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 a user. This can be done by doing:

    Before Airlock WAF 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 WAF 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 WAF Update/Hotfix those files are configured as expected.

  10. Adding users
Knowledge Base Categories: