HTTP Headers Access

This kind of access mechanism is possible when the AuthN/AuthZ process is delegated to an upstream component (a Shibbolett agent deployed in an Apache Web Server for instance).

It supposes that the AuthN/AuthZ module inserts credentials information in headers of the HTTP request.

The schema below represents the cinematic behind this kind of access:

The following procedure should work:

• With Tomcat 8 and Tomcat 9
• Under Windows and Linux

To ensure this installation procedure, you should first download this archive in the Web Server (i.e. the server that hosts the iGRC webapp).

This archive contains:

• The HTTP Headers Tomcat Valve (httpheadersauthenticator-1.1.jar)
• A configuration Authenticator.properties file in a dedicated folder (to deploy as-is in the right destination, see later)

It is also admitted that:

• Tomcat instance is installed and available
• The operator has RW privileges in needed files and folders to proceed to the installation

The goal of the manipulation is to install an Authenticator and configure the Tomcat to use it in order to manage the HTTP Headers received from the Web Server and, from it, build/set the Principal to send to the iGRC webapp.

In the following procedure, we will use below variables:

Here is the steps to follow:

• Unzip the archive in the <TOMCAT_LIB_FOLDER_HOME> folder

Under <TOMCAT_CONF_FOLDER> folder

• Create a file HTTPHeadersAuthenticator.properties with the below content
• You should set the value according to your context

defaultRoleList=user
loginHttpHeader=<HTTP_HEADER_LOGIN_FIELD>
rolesHttpHeader=<HTTP_HEADER_MEMBERS_FIELD>
rolesSeparator=<HTTP_HEADER_MEMBERS_SEPARATOR_FIELD>
roleMapping=<HTTP_HEADER_ROLE_MAPPING_FILE>

Under <TOMCAT_CONF_FOLDER> folder

• Create a <HTTP_HEADER_ROLE_MAPPING_FILE> file
• Fill it according to your context and following the below format

<SHIBBOLETT_ROLE1>=<PORTAL_ROLE1>
<SHIBBOLETT_ROLE2>=<PORTAL_ROLE2>
...
<SHIBBOLETT_ROLEn>=<PORTAL_ROLEn>

Copy the web.xml file from the <WEB_INF_WEBAPP_FOLDER> folder in the <TOMCAT_CONF_FOLDER> folder

• Rename the copy as <WEBAPP_NAME>-web.xml
• Set the rights accordingly
• At the end of the file, in the web-app element, update the Authentication method (see below)

<login-config>
                <auth-method>HTTPHEADERS</auth-method>
</login-config>

• Create a file <WEBAPP_NAME>.xml under <TOMCAT_CONF_FOLDER>/Catalina/localhost folder with the below content
  • Set the rights accordingly

<?xml version="1.0" encoding="UTF-8"?>
<Context override="true" altDDName="conf/<WEBAPP_NAME>-web.xml">
        <Manager pathname="" />
</Context>

• Open the server.xml file in the <TOMCAT_CONF_FOLDER> folder
  • If present, remove the org.apache.catalina.realm.UserDatabaseRealm realm
  • If, after this removal, the org.apache.catalina.realm.LockOutRealm realm is empty, you can also remove it

<!-- Use the LockOutRealm to prevent attempts to guess user passwords
    via a brute-force attack -->
    <Realm className="org.apache.catalina.realm.LockOutRealm">
    <!-- This Realm uses the UserDatabase configured in the global JNDI
    resources under the key "UserDatabase".  Any edits
    that are performed against this UserDatabase are immediately
    available for use by the Realm.  -->
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
        resourceName="UserDatabase"/>
<!-- </Realm> -->

To debug the authentication settings, you can add the following information at the bottom of your <TOMCAT_CONF_FOLDER>/logging.properties:

# To see debug messages for HttpHeader Valve, uncomment the following line
com.brainwave.utils.level = ALL

Where all steps have been performed, you can restart the Tomcat service. Logs should be visible in catalina log files.

Ensure the Tomcat is listening only on localhost and reachable only from Apache for HTTP protocol. You can make this check in the <TOMCAT_CONF_FOLDER>/server.xml.

http_headers_configuration.zip