Set up high availability configuration for Identity Manager

If you have more than one Identity Manager node, you need to set up high availability configuration for Smart ID Identity Manager.

There are two options, you can either set up a Windows Failover Cluster or a load balancer, using the Apache HTTP server. Both options are described in this article. See also High availability architecture for Identity Manager.

This article is valid for legacy systems (PRIME).

Prerequisites

A high availability license is required.

Option: Set up failover cluster

To set up an active-passive failover cluster using Microsoft Windows Failover Cluster Services:

Install a Windows Failover Cluster according to the install guide provided on Microsoft Technet: Failover clustering deployment.
Note the following:
1. The common fileshare that the Windows Failover Clustering Services describes is not needed.
2. The service that needs to be monitored for failover by Windows Cluster Service is the Apache Tomcat Service.

Install identical Tomcat nodes

To install identical Tomcat nodes:

Install a complete PRIME system on one node, including Tomcat, Java, PRIME applications, and database connection.
Copy the setup from the first node to other nodes, to make sure that all components are exactly the same on all nodes.

Option: Set up load balancer

Prerequisites

For the general requirements for Identity Manager, see IDM 23.10.3 - Requirements and interoperability.

The following additional components are required:

Apache HTTP Server 2.4 (Tested on Version 2.4.17)
mod_jk 1.2 (tested on Version 1.2.41)

Supported platforms for the high availability configuration:

Windows 7, Windows 8.1, Windows Server 2008/2008 R2/ 2012/ 2012 R2
Linux

This article will focus on setup on a Windows Environment with the precompiled Apache Lounge Distribution. Setup with other Apache HTTP packages and under different Linux distributions will differ regarding folders, file locations, etc.

Set up standard Apache HTTP server

For load balancing with the Apache HTTP Server, the module mod_jk is recommended. It is also possible to use the module mod_proxy.

Differences between mod_jk and mod_proxy:

mod_jk relies on an AJP connection between Apache Tomcat and Apache HTTP Server, AJP is a binary, proprietary protocol, With AJP a slightly better performance can be expected and the setup is much easier in contrast to mod_proxy. It also will forward additional metadata (e.g. client certificates for HTTPS client Auth) to the server. The drawback on the other hand is that the communication between Tomcat and HTTP Server can’t be encrypted. This drawback should be acceptable because both servers are backend systems.
mod_proxy relies on a proxy http(s) connection from HTTP Server to Tomcat. This means that the connection can be encrypted also, but setup is much more complex and metadata from the original HTTP request won’t reach the Tomcat.

To do a standard Apache HTTP server setup:

Download and install the Apache HTTP server. See Apache HTTP Server Project for downloads and install guide.
Example:
With the Apache Lounge Distribution, the file unzips to the folder C:\Apache24. The Windows service can be installed with the following command:
TEXT
```
httpd.exe -k install
```
When the service is running, call http://localhost in your browser to test the server. You should get a website saying "It works".
The mod_jk extension is not part of the standard delivery, so it needs to be installed separately:
Copy the file mod_jk.so to the subfolder modules in your Apache installation, for example C:/Apache24/modules.
Open the file httpd.conf located in the subfolder conf, for example: C:/Apache24/conf/http.conf.
Add the following line in the file, to activate the module:
TEXT
```
LoadModule jk_module modules/mod_jk.so
```
Save the file.
Restart the Apache HTTP Service.

Activate load balancer

On the Apache HTTP Server, do the following to get the Load balancer running:

Create a workers.properties file and place it together with httpd.conf in c:\apache24\conf. Edit the host name and port for Apache JServ Protocol (AJP), in this example 8009, to your corresponding environment.
The file workers.properties does the configuration of the different Tomcat nodes (in most cases you will have two nodes). It holds some very basic parameters like Tomcat host names, ports, but also a lot of additional things (like load balancing factor sticky session setup etc) can be defined here. The following example describes the most basic setup to get the system running, depending on the customers’ requirements it might be necessary to fine-tune this according to the official mod_jk documentation.
Example: workers.properties
TEXT
```
# workers to contact, that's what you have in your httpd.conf 
worker.list=loadbalancer,status 


#setup node1 
worker.node1.port=8009 
worker.node1.host=myTomcatHost.node1 
worker.node1.type=ajp13 
worker.node1.lbfactor=50 


#setup node2 
worker.node2.port=8009 
worker.node2.host= host=myTomcatHost.node2 
worker.node2.type=ajp13 
worker.node2.lbfactor=50 


#setup the load-balancer 
worker.loadbalancer.type=lb 
worker.loadbalancer.balance_workers=node1,node2 
worker.loadbalancer.sticky_session=true 
worker.loadbalancer.sticky_session_force=true 
worker.loadbalancer.set_session_cookie=true 


# Status worker for managing load balancer 
worker.status.type=status
```
Do the following updates in the file httpd.conf:
1. Add the following lines to the httpd.conf, to set up the mod_jk configuration for the load balancer, pointing to the corresponding file workers.properties:
  Example: httpd.conf
  TEXT
```
JkWorkersFile C:/Apache24/conf/workers.properties 


JkShmFile C:/Apache24/logs/httpd/mod_jk.shm 
JkLogFile C:/Apache24/logs/httpd/mod_jk.log 
JkLogLevel debug 
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " 


#global JkMounts - you can remove them when using virtual hosts 
JkMount /prime_explorer/** loadbalancer 
JkMount /prime_ussp/** loadbalancer 


# optionally add the status mount point 
# JkMount /jkmanager/* status
```
  This example assumes that Identity Manager and Smart ID Self-Service are deployed as prime_explorer and prime_ussp webapps on both Tomcats.
  The jkmanager is deactivated in this setup. To activate it, remove the # in the beginning of the line. Consider that the jkmanager should be restricted only to admins, for example by using a certain authenticate port. The jkmanager allows to maintain the nodes.
2. If the Identity Manager service should run on certain ports, for example in an HTTPS environment, set up a virtual host in httpd.conf.
  The following example describes a setup for HTTPS.
  Example: virtual host in httpd.conf
  TEXT
```
Listen 444 
NameVirtualHost *:444 
<VirtualHost *:444> 
	ServerName nexusprime.local 
	SSLEngine on 
	SSLCertificateFile "c:/apache24/conf/primeServerCert.cer" 
	SSLCertificateKeyFile "c:/apache24/conf/ primeServerCert.key" 
#SSLVerifyClient require 
#SSLVerifyDepth 1 
#SSLCACertificateFile "c:/apache24/conf/ primeTrustedCA.cer" 


JkMount /prime_explorer/** loadbalancer 
JkMount /prime_ussp/** loadbalancer 
#JkMount /jkmanager/* status 


</VirtualHost>
```
  This setup provides an HTTPS Connection on Port 444. For client authentication you need to activated the three lines marked with #. If you use client certificates, you might want to remove the global JkMount entries shown in the first example.
  When using SSL client authentication, you might want to forward the certificates to the PRIME system. Please check the AJP manual for the corresponding parameters.

Install identical Tomcat nodes

All Tomcat nodes must have exactly the same setup. Especially the deployment of the applications (in webapps) and the server-side configuration in these applications must be identical, for example, database.properties and log4j.xml. It is also a good idea to keep server.xml and Java OS Environment identical.

Also, communication to subsystems must be available in the same way on each node, for example File Export, LDAP connection, and PKI connections.

To install identical Tomcat nodes:

Install a complete Identity Manager system on one node, including Tomcat, Java, Identity Manager applications, and database connection.
Copy the setup from the first node to other nodes, to make sure that all components are exactly the same on all nodes.
Verify that each Identity Manager instance on each node works properly on its own.

Configure each Tomcat node for loadbalancing

To configure the node name and activate the AJP connector, do the following for each node:

Open server.xml.
In server.xml, go to the Engine element. Edit the name in the parameter jvmRoute, to tell Tomcat which node to listen to.
The node names are defined in workers.properties. In the example above it is node1 and node2.
Example: Engine element in server.xml
TEXT
```
<Engine name="Catalina" defaultHost="localhost" jvmRoute="node1">
```

The jvmroute will also be picked up by object history to make sure every node has their own history chain. For other clustering techniques see: Chained signature for object history in Identity Manager section Clustering.

The AJP connector itself is normally also activated by default on Tomcat. In server.xml, verify that the following Connector entry is present, and that :
Example: Connector element in server.xml
TEXT
```
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
```
If you want to avoid that someone can access one of the Tomcat nodes directly, deactivate all the other HTTP- or HTTPS-based connectors on the Tomcats.
When the Apache HTTP Server and the Tomcats are successfully configured, the Loadbalancer is ready to use.

It does not matter in which order the services are started, the connections are established or re-established on demand.

To see the status of each node, check the jkmanager.

Additional information

Useful links