You are here

Customizing administration roles for Airlock 4.2

Affects version(s): 
4.2 all versions

 

Introduction

Airlock 4.2 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 4.2 updates could overwrite them. 

Custom roles for access control can be added by editing /airlock/configuration/gui/acl.xml. After a new installation neither the directory gui nor the the xml configuration file (acl.xml) exists. So, create this file and directory and set the permission properly.

  1. Setupmkdir -p /airlock/configuration/gui
    touch /airlock/configuration/gui/acl.xml
    chown alecinst:alec /airlock/configuration/gui/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 GUI

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

    /opt/slt/ses/alec/webclient/tomcat/webapps/airlock/WEB-INF/applicationContext-security.xml

    and search for "objectDefinitionSource":

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

  8. Restart GUI
     After those changes the Airlock Configuration Center must be restarted to reload the new configuration:
    svcadm disable svc:/site/slt_alec_webclient
    svcadm enable svc:/site/slt_alec_webclient
  9. Adding group to UserManager 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/slt/ses/alec/core/bin/UserManagerAdd 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/slt/ses/alec/webclient/tomcat/webapps/airlock/WEB-INF/applicationContext-security.xml and /opt/slt/ses/alec/core/bin/UserManager 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 UserManager script and follow the instructions:
    /opt/slt/ses/alec/core/bin/UserManager
Knowledge Base Categories: