This documentation is for older WSO2 products. View documentation for the latest release.
Page Comparison - Load Balancing Identity Server (PDP cluster) using Apache HTTP Server (v.3 vs v.4) - Clustering Guide 4.2.0 - WSO2 Documentation

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

This section explains how to use Apache HTTP server to load balance the WSO2 Identity Server cluster nodes.


  1. You need to install Apache HTTP server. If you are using Linux, you can easily install it by using apt-get, zypper, or another installation program as follows:

    Code Block
    apt-get install apache2
  2. You need to enable the necessary modules. These are:



    If a2enmod or a similar command is available in your Linux version, you can use it to enable these modules.

  3. You need a key and certificate files to configure SSL communication with Apache HTTP server.

The following are the summarized steps to create a key and a certificate using a self signed Certificate Authority (CA). Here default openssl configurations are used (in Ubuntu, the default openssl configuration file can be found at /etc/ssl/openssl.cnf).

  1. Create a local Certificate Authority (CA) using OpenSSL.
    1. First build the CA key using the following command:

      Code Block
      $ openssl genrsa -des3 -out ca.key 1024 (key name as ca.key)
    2. Next build the certificate of CA. This is the CA’s certificate and it can be publicly available.

      Code Block
      $ openssl req -new -x509 -days 365 -key ca.key -out ca.crt (created CA key location is given and certificate name given as ca.crt)
  2. Generate a server key and CSR (Certificate Signing Request).
    1. Private key for Apache HTTPD Server is built with the default openssl configuration.

      Code Block
      $ openssl genrsa -des3 -out server.key 1024 (key name as server.key)
    2. Then CSR is created to be signed by a Certificate Authority.

      Code Block
      $ openssl req -new -key server.key -out server.csr (created server key location is given and csr name is server.crt)
  3. Sign the certificate signing request (CSR) with the self-created Certificate Authority(CA).

    Code Block
    $ openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt (CA and server keys location are given, certificate name as server.crt)
  4. Make a server.key which does not cause Apache to prompt for a password.

    Code Block
    $ openssl rsa -in server.key -out server.key.insecure
    $ mv server.key.insecure server.key (rename key to server.key )

Now you have the key file; the server.key and certificate file, and the server.crt file. Now use the following steps to balance the WSO2 Identity Server load using Apache HTTP server.

Step 1

Configure virtual host containing following sample content (in Ubuntu you can create it inside etc/apache2/sites-available directory).

Code Block
<IfModule mod_proxy.c>
	<VirtualHost *:443>
 		ServerName localhost
		ServerAlias localhost
 		ProxyRequests Off
 		SSLEngine On
 		SSLProxyEngine On
 		SSLCertificateFile /home/asela/Security/162/server.crt
 		SSLCertificateKeyFile /home/asela/Security/162/server.key
		<Proxy *>
 			Order deny,allow
 			Allow from all
		ProxyPass /balancer-manager !
 		ProxyPass / balancer://wso2.identity.domain/ lbmethod=byrequests stickysession=JSESSIONID
 		ProxyPassReverse / https://localhost:9443/
 		ProxyPassReverse / https://localhost:9444/
		<Proxy balancer://wso2.identity.domain>
 			BalancerMember https://localhost:9443 route=isNode1 loadfactor=1
 			BalancerMember https://localhost:9444 route=isNode2 loadfactor=1

Important notes of this configurations.

  • Assume that Apache HTTP server and WSO2 Identity Server cluster (2 nodes with HTTPS port 9443 and 9444) are running in same machine (localhost).
  • All the requests that come to the 443 port are load balanced to 9443 and 9444.
  • ServerName and ServerAlias parameters are set to “localhost”.
  • SSL is enabled for both client side (for clients who call the Apache HTTP server) and back end servers (for WSO2 Identity Server nodes). 


    Certificate validation is not enabled for backend services.

  • A proxy is created to send all requests to wso2.identity.domain load balancer.
  • In the wso2.identity.domainload balancer configuration, members (WSO2 Identity Server nodes) are defined with the following two parameters
    • route – This defines the jvmRoute parameter which is configured in the corresponding WSO2 Identity Server node. This parameter is needed to achieve the sticky session.
    • loadfactor – This defines how load must be shared between two nodes. It configures equal load for both two nodes.

You can find more details from Apache HTTP server docs and you can define your own configuration. The virtual host configuration, which is defined above, is just a sample one.

Step 2

Enable virtual host configuration. If a2ensite or a similar command is available in your Linux version, you can use it to enable the configuration.

Step 3

  1. Restart Apache HTTP server.
  2. In Linux, use:

    Code Block
    /etc/init.d/apache2 restart

Step 4

Restart WSO2 Identity Server nodes with proper jvmRoute Ids (since we have configured this as the virtual host configuration).

Pass the corresponding jvmRoute id as system property value.

For example, in Linux before the WSO2 IS server is started you can set the following:

Code Block
export JAVA_OPTS='-DjvmRoute=isNode1'

Or you can set this in the or wso2server.bat. In the script file, you can set it using the following:

Code Block
-DjvmRoute=isNode1 \

Step 5

Change your client application (web app or Java client) to connect to the Apache HTTP server.


The client needs to communicate with the Apache HTTP server using SSL. Therefore it must be trusted by your client application. So you need to export the CA certificate of the Apache Apache HTTP server into the client’s trust store.