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 : https://wso2.com/ProxyContextPath/products
Back-end service url path : https://wso2.com/products
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 -> https://10.100.1.1:9443/carbon
URL of the reverse proxy -> https://prod.abc.com/appserver/carbon
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
https://apim.wso2test.com
https://esb.wso2test.com
https://as.wso2test.com
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 https://wso2test.com and in the example the products lies on proxy paths
API Manager ----> https://wso2test.com/apimanager
Enterprise Service Bus ----> https://wso2test.com/esb
Application Server ----> https://wso2test.com/appserver
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;
server_name wso2test.com;
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/ {
proxy_pass https://as.wso2test.com:9443/;
proxy_redirect https://as.wso2test.com:8243/ https://wso2test.com:8243/appserver/;
}
}
server{
listen 8280;
server_name wso2test.com;
client_max_body_size 100M;
root /usr/share/nginx/www;
index index.html index.htm;
location /appserver/ {
proxy_pass http://as.wso2test.com:9763/;
proxy_redirect http://as.wso2test.com:8280/ http://wso2test.com:8280/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 wso2test.com. To test in a local machine you need to put the wso2test.com , as.wso2.com into the /etc/hosts entry as follows.
127.0.0.1 wso2test.com
127.0.0.1 as.wso2test.com
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.
wso2test.com
Set the MgtHostName as as.wso2.com
as.wso2test.com
Set the ProxyContextPath as the appserver. This is the proxy path string which will appear in the management console, web apps and services urls.
appserver
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.
https://wso2test.com:8243/appserver/carbon/
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.
Conclusion
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.
References
[1].http://nginx.org/
[2].https://www.digitalocean.com/community/tutorials/how-to-create-a-ssl-certificate-on-nginx-for-ubuntu-12-04
