Ads 468x60px

Tuesday, December 23, 2014

Adding a custom proxy path for WSO2 Carbon 4.3.0 Based Products

The objective of this article is to give a comprehensive guide on, custom proxy paths, why we need a custom proxy path and how to enable a custom proxy path for WSO2 products. This feature was introduced in Carbon 4.3.0 release.

Custom proxy paths

Custom proxy path is used when mapping a proxy url pattern into a back-end url pattern.
For example lets consider

Proxy entry url path :   
Back-end service url path :

In the above example “ProxyContextPath” is the proxy context that was added for the target service url. When a client sends a request to the proxy entry url path, the request has to be directed to the back-end service url where the original service lies; and finally the client has to be served via the requested proxy entry url path. The mapping between the proxy url path and the back-end service url path can be resolved fronting the service to a reverse proxy server.

Why we need a custom proxy path?

In the current WSO2 server implementations web context root can be used to change the context root of the management console. The limitation of using the web context root is that it can't be used to change the context root of services.

Proxy context path is a useful parameter to add a proxy path when a Carbon server is fronted by reverse proxy. In addition to the proxy host and proxy port this parameter allows you add a path component to external URLs. e.g.
        URL of the Carbon server ->
        URL of the reverse proxy ->

This specially required whenever you are generating URLs to displace in     Carbon UI components. When hosting multiple wso2 products under the same domain name, the normal scenario is to host them under sub domains.

For e.g. If we have API Manager, ESB and Application Server, the urls would be

Also this feature would enable customers to expose several WSO2 products under the same domain name. Following diagram describes this concept.

All the products are under a single domain and in the example the products lies on proxy paths

API Manager           ---->
Enterprise Service Bus ---->
Application Server       ---->

Configure WSO2 Application Server to add a proxy context path

In this article adding and configuring proxy context path for WSO2 Application Server 5.2.1 is discussed. Before configuring the Application Server, a reverse proxy server need to be installed and configured. For this article we are going to use the nginx reverse proxy server[1].

First install the nginx server and configured in your deployment server machine.

sudo apt-get install nginx

Then create a folder called ssl inside /etc/nginx and lets create the ssl certificates inside this folder.

sudo mkdir /etc/nginx/ssl
cd /etc/nginx/ssl

Then create the server key and certificates.

First create the private key. A pass phrase is prompt when creating the private key.

sudo openssl genrsa -des3 -out server.key 1024

Next create the certificate signing request

sudo openssl req -new -key server.key -out server.csr

Fill in the required details. Most important entry is the Common Name. Enter the domain name or the ip address if there is no domain name.

Next step is to sign the SSL certificate created. Use the following command to sign.

sudo openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Now creating the certificate is completed and the last step is to setup the virtual host to display the new certificate.

Create a copy of the default sites-enabled configuration

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/wso2

Now create a symbolic between the sites-enabled directory and sites-available directory.

sudo ln -s /etc/nginx/sites-available/wso2 /etc/nginx/sites-enabled/wso2

Now the host is activated, and open up the /etc/nginx/sites-enabled/wso2 and enter the following configurations.

server {
listen 8243;
    client_max_body_size 100M;

    root /usr/share/nginx/www;
    index index.html index.htm;

    ssl on;
    ssl_certificate /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;

    location /appserver/ {


    listen 8280;
    client_max_body_size 100M;

    root /usr/share/nginx/www;
    index index.html index.htm;

    location /appserver/ {

In the nginx configuration for https requests with the /appserver/* pattern, the requests are directed to the /* pattern and the when the service is served to the client it resolves the url pattern to /appserver/*. This is same for the http requests also.

Save the file and Restart the nginx server using the following command and that's done with the nginx configurations.

    sudo service nginx restart

In the configuration https , http requests are listening on the 8243 and 8280 respectively. Server Name is set to To test in a local machine you need to put the , into the /etc/hosts entry as follows.

Then lets configure the WSO2 Application Server 5.2.1. First Download the product and extract it to your machine. Lets consider WSO2AS-Home as the extracted directory.

Open the /repository/conf/carbon.xml and do the following configuration changes.

Set HostName as the hostname defined in the nginx configuration.

Set the MgtHostName as

Set the ProxyContextPath as the appserver. This is the proxy path string which will appear in the management console, web apps and services urls.


As mentioned in nginx configuration section the https, http requests are listening on the 8243 and 8280; but by default WSO2 products are listening on the 9443 and 9763. In this particular article 8243 and 8280 configured as the proxy ports. Whenever the incoming requests are coming through the 8243 and 8240 they are proxied to the 9443 and 9763 ports.

To enable proxy ports open the /repository/conf/tomcat/catalina-server.xml file and add the following two entries.


proxyPort Configuration in catalina-server.xml file

That's all for the configuration. Now start the server and enter the following url in a browser.

You'll redirect to the login page, give the admin credentials and log into the server. You'll find the proxy path for admin console, services, webapps changed to the “/appserver” proxy path.



Proxy context path is useful when a wso2 server fronted by a reverse proxy server. You can add a proxy context path along with a proxy host and a proxy port parameter. This enables UI url paths to be display in a proxy path and by enabling this proxy path, multiple products can live under a single hostname.



No comments:

Post a Comment