Integration

Introduction

We recommend to run Axon.ivy Engine behind a web front-end server (Apache httpd, Microsoft IIS, Reverse Proxy, Web Application Firewall, etc.).

In those cases the web front-end server receives all requests from the clients and forwards them to the Axon.ivy Engine which handles them. This allows to integrate the processes and applications that you are running on an Axon.ivy Engine into a company or web portal. Some web front-end server provide Single Sign On (SSO) functionality. The front-end server then is responsible to identify the user (either automatically or by login). After that the user is able to operate on all web sites that are integrated into the web front-end server.

Web Front-End Server

Figure 6.1. Web Front-End Server

The integration for Apache httpd and Microsoft IIS is technically solved by using Tomcat Connectors. More technical details about those connectors can be found on the Apache Tomcat web site.

Integration Directory

All necessary files that you need to integrate an Axon.ivy Engine into a Web Server can be found in the following directories inside the Axon.ivy Engine installation directory:

  • Apache HTTP Server for Windows (x64): misc/apache/

  • Apache HTTP Server for Linux (x64): misc/apache/

  • IIS for Windows (x64): misc/iis/

The directory that matches the platform and webserver where you plan to integrate the Axon.ivy Engine will be called integration directory in this chapter.

The integration binaries for Linux are not delivered with the Axon.ivy Engine as it is best practice to use the Tomcat Connector binaries that are provided by the Linux distribution. See “Linux example configuration”

External base URL

Once Axon.ivy is served to clients via a front-end webserver, you must make the front-end webserver known as shown in the “ivy.webserver.yaml”. Axon.ivy will use this configuration to create absolute links that are accessible to clients (e.g. for links in task mails).

# sample ivy.yaml that configures an front-end webserver for clients.
# <a href="https://acme.com:443/">https://acme.com:443/</a> will be the absolute URL prefix for links generated by Axon.ivy
Frontend:
  HostName: acme.com
  Port: 443
  Protocol: https

Apache Integration

An Apache HTTP Server 2.x can be configured as web frontend of an Axon.ivy Engine. The communication between the Apache HTTP Server and the Tomcat from Axon.ivy is possible by using the Apache Tomcat Connector.

Windows example configuration

  1. If your Apache HTTP Server is not running on the same host as the Axon.ivy Engine then the integration directory content must be copied to the host where your Apache HTTP Server is running.

    • Copy the mod_jk binaries and the sample configuration files from the directory that matches your OS in [[Axon.ivy Engine install dir]]/misc/apache to the Apache Host under C:\Program Files\ivy

    All next steps have to be done on the host where the Apache HTTP Server is running on.

  2. Include the copied jk_module configuration in the [[Apache Install Dir]]/conf/httpd.conf. Add the following lines to do so:

    # Axon.ivy Engine Integration
    Include C:/Program Files/ivy/mod_jk.conf
  3. Replace all <path> strings in the file C:\Program Files\ivy\mod_jk.conf so that the file reflects your local paths:

    # Load mod_jk module
    LoadModule    jk_module  c:/program files/ivy/mod_jk-1.2.42-httpd-2.4.so
    # Where to find workers.properties
    JkWorkersFile c:/program files/ivy/workers.properties
    # Where to put jk shared memory
    JkShmFile     c:/program files/ivy/mod_jk.shm
    # Where to put jk logs
    JkLogFile     c:/program files/ivy/mod_jk.log
    # Set the jk log level [debug/error/info]
    JkLogLevel    info
    # Select the timestamp log format
    JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
    
    # Mount the uri "/ivy/*" to the worker AxonIvyEngine.
    JkMount  /ivy/* AxonIvyEngine
  4. If you have configured virtual hosts in your apache configuration you have to map the URI /ivy/* in all virtual host you want to integrate Axon.ivy Engine into. This can be done by copying the following line from the mod_jk.conf file to the appropriate virtual host definitions:

    JkMount /ivy/* AxonIvyEngine

    Copy this to the appropriate virtual host definitions, e.g.:

    <VirtualHost *:80>
        ServerAdmin webmaster@ivy.soreco.wan
        DocumentRoot "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/docs/ivy.soreco.wan"
        ServerName ivy.soreco.wan
        ServerAlias www.ivy.soreco.wan
        ErrorLog "logs/ivy.soreco.wan-error.log"
        CustomLog "logs/ivy.soreco.wan-access.log" common
        JkMount /ivy/* AxonIvyEngine
    </VirtualHost>

  5. Define the hostname and port, where the Axon.ivy Engine is running. Adjust the content of the file C:\Program Files\ivy\worker.properties to do so.

    worker.list=AxonIvyEngine
    worker.AxonIvyEngine.type=ajp13 
    worker.AxonIvyEngine.port=8009
    worker.AxonIvyEngine.host=ivyserver
  6. Update the external base URL as shown in the “ivy.webserver.yaml”

  7. Restart the Apache HTTP Server and the Axon.ivy overview page should be accessible under http://apacheHostName/ivy

Linux example configuration

Within this example an Apache HTTP Server is configured so that it can connect to the Tomcat of an Axon.ivy Engine. The configuration step descriptions are generic and can be used under any Linux distribution. But the concrete examples assume that an Ubuntu distribution is installed as Operating System.

  1. Install the latest Tomcat Connector (mod_JK) by console.

    sudo apt install apache2 libapache2-mod-jk
  2. Enable the new module

    sudo a2enmod jk
  3. Update the worker.properties file according to the examples in the [[Axon.ivy Engine install path]]/misc/apache/. The following example content would connect to an Axon.ivy Engine on the host "ivyserver" under the default AJP port 8009.

    /etc/libapache2-mod-jk/worker.properties:

    worker.list=AxonIvyEngine
    worker.AxonIvyEngine.type=ajp13 
    worker.AxonIvyEngine.port=8009
    worker.AxonIvyEngine.host=ivyserver
  4. Mount the Axon.ivy Engine in the virtual host definition of the Apache HTTP Server. The context URI must match the context of the Axon.ivy Engine.

    /etc/apache2/sites-available/default:

    <VirtualHost *:80>
        ...
        #Mounts the URI /ivy/* to the worker AxonIvyEngine
        JkMount /ivy/* AxonIvyEngine
    </VirtualHost>

    Tip

    If the Apache HTTP Server is used as Load Balancer for a clustered Axon.ivy Engine installation, the JK Status Manager can be used to display debugging informations. The Manager is accessible when it is mounted in the virtual host definition configuration.

    <VirtualHost *:80>
        ...
        #Mounts the URI /jkmanager/* to the JK Status Manager interface.
        JkMount /jkmanager/* jkstatus
    </VirtualHost>

  5. Update the external base URL as shown in the “ivy.webserver.yaml”

  6. Restart the Apache HTTP Server and the Axon.ivy overview page should be accessible under http://apacheHostName/ivy

Change context URI /ivy/

You might like to make the Axon.ivy engine accessible under a custom context URI other than /ivy.

  1. Change the context name of Axon.ivy as shown in the “ivy.webserver.yaml”

    # sample ivy.yaml that configures a different context:
    # so Axon.ivy will be accessible trough <a href="http://localhost/workflow">http://localhost/workflow</a>
    WebServer.IvyContextName: workflow
    
  2. Change the context name of the Apache HTTP Server by changing the last line of the mod_jk.conf configuration file:

    #JkMount  /ivy/* AxonIvyEngine 
    JkMount  /workflow/* AxonIvyEngine
  3. If you have a virtual host configuration, the JkMount command with the new context URI must also be applied to the virtual host definition:

    <VirtualHost *:80>
        ...
        JkMount /workflow/* AxonIvyEngine
    </VirtualHost>

Microsoft IIS Integration

Important

To successfully integrate Axon.ivy Engine into Microsoft Internet Information Server (IIS) it is important that you exactly execute all the integration steps described below. If the integration does not work verify each integration step again.

IIS 8 (Windows Server 2012)

Note

There is a batch script autoconfig.bat in the folder misc\iis of your engine installation, which installs and configures the IIS automatically on a Windows 2012 Server.

If you are setting up a new IIS Server you can use this script instead of following the instructions below.

  1. If your Microsoft Internet Information Server is not running on the same host as the Axon.ivy Engine then copy the integration directory to the host where your IIS is running. All next steps have to be done on the host the IIS is running on.

  2. Allow the user groups Authenticated Users and IUSR to have Full control permission on the integration directory.

  3. Install Features

    Note

    Instead of installing the features manually you can run the following command which ensures that all necessary IIS Features are installed:

    PKGMGR.EXE /iu:IIS-WebServerRole;IIS-WebServer;IIS-CommonHttpFeatures;IIS-StaticContent;IIS-DefaultDocument;IIS-DirectoryBrowsing;IIS-HttpErrors;IIS-ApplicationDevelopment;IIS-CGI;IIS-ISAPIExtensions;IIS-ISAPIFilter;IIS-HealthAndDiagnostics;IIS-HttpLogging;IIS-RequestMonitor;IIS-Security;IIS-WindowsAuthentication;IIS-RequestFiltering;IIS-Performance;IIS-HttpCompressionStatic;IIS-WebServerManagementTools;IIS-ManagementScriptingTools;IIS-ManagementService

    Open the Server Manager (Start > Server Manager). Select the Web Server (IIS). Validate that under the Role Services the services CGI, ISAPI Extensions and ISAPI Filters are installed. If this is not the case select the menu Add Role Services to install the missing services.

  4. Feature delegation

    Note

    The following command automatically sets the feature delegation:

    powershell -ExecutionPolicy unrestricted -ImportSystemModules Set-WebConfiguration //System.webServer/handlers -metadata overrideMode -value Allow -PSPath IIS:/

    Open the Internet Information Services (IIS) Manager (Start > Internet Information Services (IIS) Manager). In the Connections pane select the node that represent your machine. In the Feature View open the Feature Delegation entry.

    Ensure that the Delegation of the Handler Mappings are set to Read/Write. Use the menu Read/Write on the Actions pane to change the Delegation to Read/Write.

  5. Virtual ivy directory

    Note

    The following commands automatically creates the virtual directory ivy:

    set path=%path%;%windir%\system32\inetsrv

    appcmd.exe add vdir /app.name:"Default Web Site/" /path:/ivy /physicalPath:<replace this with the path to the integration directory>

    In the Connections pane navigate to the Web Site you want integrate the Axon.ivy Engine into. Use the context menu Add Virtual Directory ... of the Web Site to add a new Virtual Directory. A dialog opens. Configure the Alias of the Virtual Directory with ivy and the Physical path of the Virtual Directory with the path of the integration directory. Click OK to close the dialog and create the Virtual Directory:

  6. Handler Mapping Permissions

    Note

    The following command automatically sets the feature permission for the ivy virtual directory:

    appcmd.exe set config "Default Web Site/ivy" /section:system.webServer/handlers /accessPolicy:Read,Write,Execute

    Select the new created Virtual Directory ivy in the Connections pane and open the Handler Mappings entry in the Feature View:

    In the Actions pane select the Edit Feature Permissions ... menu:

    On the Edit Feature Permission dialog select all three permission and click OK:

  7. Configure Error Page

    Note

    The following command automatically configures that the detailed error page of the Engine is shown:

    appcmd.exe set config "Default Web Site/ivy" /section:system.webServer/httpErrors /errorMode:Detailed

    Tip

    See the “web.xml” for more information about this configuration.

    Select the new created Virtual Directory ivy in the Connections pane and open the Error Pages entry in the Feature View:

    Right click and select Edit Feature Settings... or select the same from the Actions pane (in the right hand side)

    Select the Detailed errors radio button and click on OK

  8. Install ISAPI filter

    Note

    The following command automatically adds the ISAPI Filter:

    appcmd.exe set config /section:isapiFilters /+[@start,name='Tomcat',path='<replace this with the path to the integration directory>\isapi_redirect-1.2.42.dll']

    Select the Web Site in the Connections pane and open the ISAPI Filters entry in the Feature View:

    In the Actions pane select the Add ... menu:

    On the Add ISAPI Filter dialog configure the Filter name with Axon.ivy Engine and the Executable with the path of the isapi_redirect-1.2.42.dll located in the integration directory. Click OK to add the ISAPI Filter:

  9. Change ISAPI filter restriction

    Note

    The following command automatically adds the ISAPI Restriction:

    appcmd.exe set config /section:isapiCgiRestriction /+[@start,description='Tomcat',path='<replace this with the path to the integration directory>\isapi_redirect-1.2.42.dll',allowed='true']

    In the Connections pane select the node that represent your machine and open the ISAPI and CGI Restrictions entry in the Features View:

    In the Actions pane select the Add ... menu:

    On the Add ISAPI or CGI Restriction dialog configure the ISAPI or CGI path with the path of the isapi_redirect-1.2.42.dll located in the integration directory. As Description use Axon.ivy Engine. Select the Allow extension path to execute check box. Click OK to add the ISAPI or CGI Restriction:

  10. If your Microsoft Internet Information Server is not running on the same host as the Axon.ivy Engine or if you have changed the AJP port of the Axon.ivy Engine then open the file worker.properties inside the integration directory in a text editor. Change the following line if you have changed the AJP port to another value than 8009:

    worker.AxonIvyEngine.port=8009

    Change the value localhost in the following line to the host where your Axon.ivy Engine is running if your Microsoft Internet Information Server is not running on the same host as the Axon.ivy Engine:

    worker.AxonIvyEngine.host=localhost
  11. Update the external base URL as shown in the “ivy.webserver.yaml”

  12. Check if the integration is working by opening a web browser on the address http://<your host>/ivy/

Change context URI /ivy/

You might like to make the Axon.ivy engine accessible under a custom context URI other than /ivy.

  1. Change the context name of Axon.ivy as shown in the “ivy.webserver.yaml”

    # sample ivy.yaml that configures a different context:
    # so Axon.ivy will be accessible trough <a href="http://localhost/workflow">http://localhost/workflow</a>
    WebServer.IvyContextName: workflow
    
  2. Change the context name of the Microsoft IIS by changing the last line of the uriworkermap.properties configuration file:

    #/ivy/* AxonIvyEngine 
    /workflow/*=AxonIvyEngine

Access multiple Axon.ivy Engines through one IIS

Multiple Axon.ivy Engine instances can be accessed through a single IIS server. This is especially useful if multiple Axon.ivy versions must be accessible during a migration phase. The following explanation shows a solution for the scenario, where a legacy Xpert.ivy 3.9 Server and an Axon.ivy 5.x Engine must be accessible through a single IIS host.

  1. Make the newer Axon.ivy Engine accessible through the IIS as if only one engine would be behind the IIS. For detailed instructions follow “Microsoft IIS Integration”.

    In our scenario the integration directory from the Axon.ivy 5.x Engine was used to make the engine instance accessible under http://localhost/ivy.

  2. The contexts of the Axon.ivy Engines must be unique. By default the context is set to /ivy/ . If different versions of ivy engines are accessed from the same IIS host, it's useful to change the contexts so that it matches the ivy version. For detailed explanation see “Change context URI /ivy/”

    In our scenario the context URI of the Axon.ivy 5.x Engine was changed to /ivy5/ and the Xpert.ivy 3.9 Server kept his default context /ivy/.

  3. All Axon.ivy Engines, which are accessed from the same IIS, must listen on a different port for AJP communication. Therefore the AJP port must be changed. This can be configured as shown in the “ivy.webserver.yaml”.

    In our scenario the AJP port of the Axon.ivy 7.x Engine was changed to 8010 and the Xpert.ivy 3.9 Server kept his default AJP port 8009.

    # ivy.yaml with AJP enabled on 8010
    AJP:
      Enabled: true
      Port: 8010
  4. The Axon.ivy Engines must be declared in the worker.properties file of the integration directory. It's important that each worker has a unique name and that they are listed in the worker.list property.

    In our scenario the worker.properties looks as follows:

    worker.XpertIvyServer3x.type=ajp13 
    worker.XpertIvyServer3x.port=8009
    worker.XpertIvyServer3x.host=ivyhostname39
    
    worker.AxonIvyEngine5x.type=ajp13 
    worker.AxonIvyEngine5x.port=8010
    worker.AxonIvyEngine5x.host=ivyhostname50
    
    worker.list=XpertIvyServer3x,AxonIvyEngine5x
  5. The contexts of the Axon.ivy Engines must be registered in the uriworkermap.properties file of the integration directory.

    In our scenario we make Axon.ivy 5.x available under http://localhost/ivy5/ and Xpert.ivy 3.9 under http://localhost/ivy. So the uriworkermap.properties file looks as follows:

    /ivy/*=XpertIvyServer3x
    /ivy5/*=AxonIvyEngine5x

Single Sign On

Axon.ivy Engine supports single sign on in Windows environments. The following preconditions must be fulfilled for single sign on:

  • The application on the Axon.ivy Engine must use Active Directory Security System

  • The Axon.ivy Engine must be integrated into a Microsoft Internet Information Server (IIS)

IIS 8 (Windows Server 2012)

Note

There is a batch script autoconfigSSO.bat in the folder misc\iis of your engine installation. This script automatically sets up SSO on a Windows 2012 Server.

If you are setting up a new IIS Server you can use this script instead of following the instructions below.

  1. Install Windows Authentication

    Note

    The following command automatically installs the Windows Authentication:

    PKGMGR.EXE /iu:IIS-WindowsAuthentication

    Open the Server Manager (Start > Server Manager). Select the Web Server (IIS). Validate that under the Role Services the service Window Authentication is installed. If this is not the case select the menu Add Role Services to install the missing service.

  2. Deactivate Anonymous Authentication

    Note

    The following command automatically deactivates the Anonymous Authentication:

    set path=%path%;%windir%\system32\inetsrv

    appcmd.exe set config "Default Web Site/ivy" -section:system.webServer/security/authentication/anonymousAuthentication /enabled:"False" /commit:apphost

    Open the Internet Information Services (IIS) Manager (Start > Internet Information Services (IIS) Manager). In the Connections pane select the ivy Virtual Directory node. In the Feature View open the Authentication entry. Select the Windows Authentication and use the menu Enable in the Actions pane to enable Windows Authentication.

    Make sure that all other authentication modes such as Anonymous Authentication or Digest Authentication are disabled, otherwise IIS will use those authentication modes and Single Sign On will not work.

  3. Activate Windows Authentication

    Note

    The following command automatically activates the Windows Authentication:

    appcmd.exe set config "Default Web Site/ivy" -section:system.webServer/security/authentication/windowsAuthentication /enabled:"True" /-"providers.[value='Negotiate']" /commit:apphost

    Remove all providers expect NTLM from Windows Authentication, otherwise Single Sign On may not work with the RIA clients.

Basic Authentication

In the following situations Basic Authentication is required:

  • to use the Axon.ivy Mobile App

  • to provide REST services which require authentication

IIS 8 (Windows Server 2012)

Note

There is a batch script autoconfigBasicAuth.bat in the folder misc\iis of your engine installation. This script automatically sets up Basic Authentication on a Windows 2012 Server.

If you are setting up a new IIS Server you can use this script instead of following the instructions below.

  1. Install Basic Authentication

    Note

    The following command automatically installs Basic Authentication:

    PKGMGR.EXE /iu:IIS-BasicAuthentication

    Open the Server Manager (Start > Server Manager). Select the Web Server (IIS). Validate that under the Role Services the service Basic Authentication is installed. If this is not the case select the menu Add Role Services to install the missing service.

  2. Activate Basic Authentication

    Note

    The following command automatically activates the Basic Authentication:

    set path=%path%;%windir%\system32\inetsrv

    appcmd.exe set config "Default Web Site/ivy" -section:system.webServer/security/authentication/basicAuthentication /enabled:true /commit:apphost

    Open the Internet Information Services (IIS) Manager (Start > Internet Information Services (IIS) Manager). In the Connections pane select the ivy Virtual Directory node. In the Feature View open the Authentication entry. Select the Basic Authentication and use the menu Enable in the Actions pane to enable Basic Authentication.

Error Handling

If the engine is running behind an IIS web server and an error occurs on the Engine IIS shows its own error page and hides the error page coming from the Engine. This is the default IIS behavior.

The Axon.ivy IIS integration script configures the IIS to show the detailed error page of the Engine (see 'Errors' in “ivy.yaml”). IIS can be reset to its default behavior (e.g. because of security reasons) with the following steps:

  1. Open the IIS manager

  2. Select the virtual directory ivy and on its Features View, double click on Error Pages

  3. Right click and select the Edit Feature Settings... or select the same from the Actions pane (on the right hand side)

  4. Select the “Detailed errors for local requests ...” radio button and click OK.

Axon.ivy Cluster Integration

Axon.ivy Engine Enterprise Edition (Cluster) works with sticky sessions. This means that the load balancer must forward all requests from a session to the same cluster node. Of course if a cluster node is no longer available then the request can be sent to another cluster node. Note, that this will cause that the user gets a new session and he loses his current work.

Load Balancing with Tomcat connector (IIS, Apache)

The Tomcat connector can be configured to act as a load balancer for multiple Axon.ivy Engine Enterprise Edition nodes. The load balancer and the cluster nodes can be configured in the workers.properties file that is located in the integration directory. An example load balancer configuration can be found in the file cluster_loadbancer_workers.properties. In this file one worker is configured called AxonIvyEngine that is a load balance worker (type=lb). The property balance_workers of the AxonIvyEngine worker defines the workers between which the load balance worker will balance the load. Here one worker per each Axon.ivy Engine Node should be configured. In the example file three workers are configured AxonIvyEngineNode1, AxonIvyEngineNode2 and AxonIvyEngineNode3.

The node workers are similar to a normal standalone worker. You can use the attributes hostname and port as explained above. Additionally they have two extra attributes called lbfactor and route. With the lbfactor attribute you can influence how the load balancer distributes the load to the workers. The higher the lbfactor of a worker relative to the other workers is the more load the worker gets.

The route attribute is necessary for realizing sticky sessions. An Axon.ivy Engine Enterprise Edition will only work correctly, if the load balancer sends all request of the same http session to the same node (sticky sessions). To support this requirement, each Axon.ivy Engine Enterprise Edition node will add a special identifier called jvm route to the http session identifier. The jvm route identifier is calculated from the host name and the Local Cluster Node Identifier. The route attribute configured on a node worker must be equal with the jvm route of the node:

worker.AxonIvyEngineNode1.route=<JVM route identifier of Node 1>

worker.AxonIvyEngineNode2.route=<JVM route identifier of Node 2>

The JVM route identifier of a cluster node can be found on the cluster node detail page for an Axon.ivy Cluster Node. This information can be retrieved as follows:

  1. Using a web browser, navigate to the main page (http://<host>:<port>/ivy) of an Axon.ivy Engine installation.

  2. Select the Cluster link in the page header.

  3. In the appearing list of cluster nodes press the name of a cluster node to see it's details.

Axon.ivy Cluster Node Details page

Figure 6.2. Axon.ivy Cluster Node Details page

More technical details about load balancing and sticky sessions can be found on the Apache Tomcat web site.

Example

Let's assume that we have an Axon.ivy Engine Enterprise Edition with two Cluster Nodes. Node 1 is installed on host ivynode1 and the AJP port is configured to 8009. Node 2 is installed on host ivynode2 and the AJP port is configured to 8010. ivynode1 is a new machine with a lot of power. ivynode2 is an old machine and we want that ivynode1 is working twice as hard as ivynode2. The jvm route of the nodes are ivynode1.soreco.ch and ivynode2.soreco.ch.

The workers.properties file must then look like this:

worker.list=XIvy

# Load Balanced Cluster Worker
worker.AxonIvyEngine.type=lb
worker.AxonIvyEngine.balance_workers=AxonIvyEngineNode1,AxonIvyEngineNode2

# 1st Axon.ivy Engine Cluster Node
worker.AxonIvyEngineNode1.type=ajp13 
worker.AxonIvyEngineNode1.port=8009
worker.AxonIvyEngineNode1.host=ivynode1
worker.AxonIvyEngineNode1.route=ivynode1.soreco.ch
worker.AxonIvyEngineNode1.lbfactor=2

# 2nd Axon.ivy Engine Cluster Node
worker.AxonIvyEngineNode2.type=ajp13 
worker.AxonIvyEngineNode2.port=8010
worker.AxonIvyEngineNode2.host=ivynode2
worker.AxonIvyEngineNode2.route=ivynode2.soreco.ch
worker.AxonIvyEngineNode2.lbfactor=1

Load Balancing with other Load Balancer Products

As described above the load balancer must ensure that all requests from the same user session is forwarded to the same cluster node. This can be done by configuring the load balancer so that all requests sent by one client IP address is always forwarded to the same cluster node (IP based stickiness). Another possible configuration is to use the Axon.ivy Session Id to provide session stickiness. The session id is provided by Axon.ivy Engine Enterprise Edition with two different methods. Either as HTTP session cookie with the name JSESSIONID or at the end of request URLs as ;jsessionid= parameter. The load balancer must be able to read the session id with both methods otherwise RIA clients will not work correctly.

Warning

Some load balancer provide session stickiness using their own HTTP session cookie. If you use this method then RIA clients will fail to start.

Web Application Firewall

A web application firewall (WAF) or web shield is a firewall which protects web applications against attacks over the HTTP protocol. Combined with an Identity and Access Management (IAM) System it also protects against unauthorized access and supports single sign on (SSO).

Single Sign On

Most WAF or IAM systems allow to configure a way how the user name of the identified user is transmitted to the web applications. With Axon.ivy Engine a typical system landscape will look like this:

Single Sign On Infrastructure using a Web Application Firewall, Identity and Access Management and Active Directory

Figure 6.3. Single Sign On Infrastructure using a Web Application Firewall, Identity and Access Management and Active Directory

The only available access point must be the WAF. Any traffic has to be routed over it. The WAF tries to protect the web application behind it (e.g. Axon.ivy Engine) from attacks. The WAF uses the IAM to identify users and to protect certain resources from unauthorized access. The IAM itself may use a directory server like Microsoft Active Directory to know users. The WAF can be configured to provide the name of the identified user either as HTTP header or HTTP cookie to the web application (Axon.ivy Engine).

On the other side Axon.ivy Engine provides a Valve that reads the user name from a HTTP header. If Axon.ivy Engine knows the user it automatically authenticates the user to the current Axon.ivy Engine session. This works best if Axon.ivy Engine also uses a directory server like Microsoft Active Directory to synchronize users. The Valve that reads the user name from a HTTP header is disabled by default. To enable it, open the file “context.xml” in the [engineDir]/webapps/ivy/META-INF directory and uncomment the following line:

<Valve className="ch.ivyteam.ivy.webserver.security.SingleSignOnValve" userNameHeader="user"/>

The attribute userNameHeader can be used to configure the HTTP header that should be read.

Warning

If you activate this Valve you must ensure that the Axon.ivy Engine cannot be accessed directly. All traffic must be routed over the WAF. Otherwise, an attacker could simple send a valid user name as header in a HTTP request and immediately has access bypassing the authentication!

Instead of sending the plain user name in a HTTP header there are multiple other ways and technologies (SAML token, Kerberos, etc.) how the WAF can transmit the current user identity to the web applications. You can support this cases by registering your own Valve in the “context.xml” file. Your value reads the current user identity from the request and puts a user principal object with the user name to it. Axon.ivy Engine will check if a user principal is set on a request and automatically searches the user and authenticates it. The code of your valve can look like this:

import java.io.IOException;
import java.security.Principal;

import javax.servlet.ServletException;

import org.apache.catalina.connector.Request;
import org.apache.catalina.connector.Response;
import org.apache.catalina.valves.ValveBase;
import org.apache.commons.lang3.StringUtils;

public class AuthValve extends ValveBase
{
  @Override
  public void invoke(Request request, Response response) throws IOException, ServletException
  {
    String userName = getUserNameFromRequest(request);
    if (StringUtils.isNotBlank(userName))
    {
      Principal userPrincipal = createUserPrincipalWith(userName);
      request.setUserPrincipal(userPrincipal);
    }
    getNext().invoke(request, response);
  }
 
  /**
   * Finds out which user was authenticated by an external instance
   * @param request
   * @return user name
   */
  private String getUserNameFromRequest(Request request)
  {
    // Example implementation:
    // Gets the user name from the HTTP Header field User.
    // Has to be changed depending on the protocol or product that you are using
    String userName = request.getHeader("User");
    return userName;
  }
 
  private Principal createUserPrincipalWith(String userName)
  {
    return new UserPrincipal(userName);
  }

  private static class UserPrincipal implements Principal
  {
    private String userName;
 
    private UserPrincipal(String userName)
    {
      this.userName = userName;
    }
 
    @Override
    public String getName()
    {
      return userName;
    }
  }
}

The method getUserNameFromRequest depends on the technology the WAF sends the user identity.