Fronting a Load Balancer with WSO2 Identity Server

5 min readMay 3, 2021

Hi all, Hope you all are staying safe in this difficult pandemic situation. As we all are moving to the new norm of living we need to carry on our day to day work even in this difficult time period. So let’s continue to share the knowledge as well. As per the topic of this blog today I am going to explain how we can configure a load balancer in front of a WSO2 Identity Server.

First things first. Let’s have a quick look at what is a load balancer and why we need that.

What and Why?

Modern applications must serve high density of user requests based on the user base that application has. Sometimes this can be hundreds of thousand or millions. These requests needs to be managed in a better way by not affecting to the application performance and also the user’s time. Maily modern applications contains several nodes to serve these high amount of user requests. But we need a mechanism to divide these requests into these nodes in an efficient way. At that part the load balancers come to the show. These load balancers can divide these high amount of requests to the corresponding application nodes. That is the main purpose and you can refer this for more information about load balancers.

For this blog I am using NGINX as the load balancer with WSO2 Identity Server 5.10.0 version. In brief WSO2 Identity Server is a fully open source identity and access management platform powered by WSO2. WSO2 Identity Server was recognized as an overall leader in KuppingerCole Leadership Compass and a strong performer in Forrester Wave. You can find more details about WSO2 Identity Server from here.

Hope you all got the basic understanding of the things that we are going to do here. Let’s dive deep to the configurations.

As the first step you will need to get the WSO2 Identity Server 5.10.0 pack. You can simply download this from the official web site or from the github repository. Now you need to install the NGINX as the load balancer. You can refer this for NGINX installation.

NGINX Configuration

Now you will need to create a private key and a certificate by executing the following command from the terminal.

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt

Now add those created private key and the certificate to the ssl directory in located in /usr/local/etc/nginx/ path (Please note that this is the path in macOS). If you don’t see a ssl directory inside the /usr/local/etc/nginx/ path you can create it and add the files to it.

Now you need to create the configuration file for the NGINX. You can create a file named as com.https.conf in /usr/local/etc/nginx/servers directory and add the following configurations.

Hostname Configuration

Now you need to add is.dev.wso2.com as a host name in the hosts file which is located in /etc/ path like the following.

127.0.0.1 localhost is.dev.wso2.com

Database Configuration

In this point you need to create databases for keeping the data for WSO2 Identity Server. For IS we need mainly three databases. They are IdentityDB, SharedDB and PrimaryUserStore. You can refer [1] and [2] to get an idea what are the tables that we need to create under each database. To keep all the things simple we can use one database to keep all the above data. Here there will be some instruction to add the databases to the IS configurations. We can do them in the next step. In this step create the databases with the relevant dbscripts only.

WSO2 Identity Server Configuration

As I mentioned in the beginning we need to download WSO2 Identity Server. After downloading make another copy on the downloaded pack and keep in a separate directory because today we are going to configure two IS nodes with the Load Balancer.

Ex : Create two directories like node1 and node2 and copy the two packs to each directory. Simple ;-)

Hereafter I will assume that you have the same directory structure as I described. So first open the deployment.toml file located in node1/wso2is-5.10.0/repository/conf directory and do the following configurations.

Change hostname from localhost to is.dev.wso2.com
Add the following.

[transport.https.properties]
proxyPort = 443

Now change the IdentityDB, SharedDB and PrimaryUserStore in the deployment.toml file as explained in [1] and [2].

Now open the deployment.toml file located in node2/wso2is-5.10.0/repository/conf directory and do the previous steps again and add the following configuration under [server] tag. By default the WSO2 IS is running in port 9443. By adding the offset =1 that node will run in 9444 port.

offset = 1

Now all the hard work is done. Now we need to get the results.

Now restart the NGINX. For Mac users, you can use the following command in the terminal.

brew services restart nginx

Now start the WSO2 Identity Server nodes if they are not already started or restart otherwise.

After successfully restart all the components we can access the Management Console and User Portal of WSO2 Identity Server. You can use the following URLs.

For management console : https://is.dev.wso2.com/carbon
For User Portal : https://is.dev.wso2.com/user-portal

Note : Prior to access user-portal you will need to change the callback URLs host name to https://is.dev.wso2.com by going in the following path from management console.

Main Menu -> Service Providers -> List -> Select Edit in the User Portal service Provider. Now go to Inbound Authentication Configuration -> OAuth/OpenID Connect Configuration and click Edit. In the resulting page you will see Callback Url* and change the hostname.

Testing Hints

You can create a user from the management console and try to login to the user-portal and do some edits in the profile. When login to the management console a log entry will be printed in the wso2carbon.log located in node[Number]/wso2is-5.10.0/repository/logs directory. You can tails both nodes wso2carbon.log files and see which node is serving for the request.
If you want to check whether the other node is also serving for the requests, we can add down keyword followed by the server IP address inside the upstream ssl.is.dev.wso2.com section like the following and restart NGINX. Now try to access the management console by checking the logs. Here you can see this request is passed to the available node.