Running BPM behind a reverse proxy or load balancer

Part 1: Introduction


Things I wish I knew about Websphere administration when I first started working with it.  

When I first started working with Websphere, I had certain expectations for how SSL and URL handling would take place.  I thought that an SSL certificate and key could be defined in a config file somewhere, or I could point a reverse proxy at the server and call it a day.  Both of these assumptions resulted in a lot of learning when it came to how BPM on a Websphere server handled HTTP traffic.  I want to share some of what I learned, in a hope to relieve potential frustration from someone else's first foray into Websphere administration.

I’m going to explain some of the specific requirements for SSL/TLS configuration, as well as walk through a very simple topology that makes use of a reverse proxy and IBM HTTP Server.  The end goal is to go from an unsightly internal hostname listening on port 9443 (the default secure port), to a cleaner external domain name, listening on port 443, with an SSL certificate signed by a trusted Certificate authority.  Note that the following topology probably isn’t production ready.  It is being used here to illustrate the interactions between the various web servers.  Here is the sample topology that I’ll setup:

Haproxy > IBM HTTP Server > BPM endpoint

Why use a reverse proxy?  There are a lot of compelling reasons to have a proxy sit in front of your websphere stack.

  1. If you want to expose more than one web service externally on a single port (443), and you only have one external IP to use, it’s one of only a few ways to accomplish that.
  2. You can make use of a wildcard certificate to simplify the addition of new domains.
  3. A reverse proxy is almost always recommended in security best practices when it comes to exposing web services out to the public.  You can minimize your attack surface in a few important ways.
  4. You can also cache objects, offload SSL, and do some load balancing, but these are outside of the scope of this piece.
  5. Most companies have one, so it’s probably already setup.  It's generally required if you want multiple servers behind a single IP (sometimes VIPS are hard to get provisioned).


What happens if you point a proxy straight at a bpm portal?

What you'll observe is that some portions of the BPM will work correctly, while others will produce unusual behavior.  You'll see things like ports switching from :443 to :9443 (or the default SSL port), or some http elements will try and load from the external url, while others load from the desired external URL.  Task notification emails will also contain an internal URL.

What happens when you use Process Designer with the external address?

It fails.  You'll see in the PD logs that it's trying to load resources from the default URL.  This is usually the internal URL if you haven't followed the steps to set the new default.

All of these symptoms remind of the old saying: "If a BPM server is in a forest with no one around: what is it's hostname?"  In part 2, I'll go over which settings need to be configured.


Part 2: BPM and Websphere configuration


Here are the relevant details for the example:

  • Split DNS setup to be authoritative for the two domains: * and *
  • Signed SSL cert for *
  • Haproxy listening on
  • IHS listening on
  • IBM BPM 8.5.6 on Websphere listening on
  • Deployment Environment = DEVENV


Let’s say we’ve installed BPM and Websphere on Red Hat 7.  What steps do we have to perform to get the server ready for IHS and Squid?  The bulk of the configuration will be done with IHS, but there is one very important step that brings this all together.  I’ll explain in detail why this is important when we get to the proxy setup.

Customizing IBM BPM to work with a web server

Keep in mind that these steps vary quite a bit from version to version.  Before running this configuration, BPM will only listen on the default virtual host for websphere.  Typically this is *:9443.  We’re going to set the default Vhost for bpm to our external hostname: on port 443.  With the deployment manager stopped, this would be the info for our example topology:

./wsadmin -conntype none -lang jython

dePath = '/Cell:/BPMCellConfigExtension:/BPMDeploymentEnvironment:DEVENV/'

webserver_vh = AdminTask.setBPMVirtualHost( [ '-de', 'DEVENV', '-name', 'webserver_vh', '-transportProtocol', 'https', '-hostname', '', '-port', '443' ] )

AdminTask.setBPMDefaultVirtualHost( [ '-de', 'DEVENV', '-name', 'webserver_vh' ] )


Part 3: IBM HTTP Server


While Websphere does have a built in webserver, it’s still recommended by IBM to make use of IBM HTTP Server.  I might write a separate post on how to install IHS, but for now, I’ll assume you have IHS installed as an unmanaged node on a separate instance.  Most of the administration can, and should be done from the websphere console on the deployment manager for the given Cell.  The hostname would be with a secure virtualhost created on port 443.  Once the plugin, httpd.conf and ssl keystore have been propogated out, you should be able to reach the BPM portal at:


Part 4: Load Balancer or Reverse Proxy setup


The setup for a load balancer is going to vary by product.  I would also keep in mind that even with a reverse proxy in front of your BPM server, there are still an assortment of security considerations.  We would recommend using the EPS toolkit with the EPS proxy.  The EPS proxy provides BPM specific access limitations for external participants.  I'll provide settings for haproxy as an example.  This is a setup where Haproxy is handling the SSL/TLS session with a wildcard certificate.  The settings are essentially: if host contains "" > route traffic to backend IHS server.


frontend front-merged
mode http
log global
option log-separate-errors
option httplog
option http-keep-alive
option forwardfor
acl https ssl_fc
http-request set-header X-Forwarded-Proto http if !https
http-request set-header X-Forwarded-Proto https if https
timeout client 120000
acl bpm hdr_sub(host) -i
use_backend bpm_http_ipvANY if bpm

frontend front-NOssl
mode http
log global
option http-keep-alive
option forwardfor
acl https ssl_fc
http-request set-header X-Forwarded-Proto http if !https
http-request set-header X-Forwarded-Proto https if https
timeout client 30000
default_backend none_http_ipvANY

backend bpm_http_ipvANY
mode http
log global
# use mailers
# level warning
email-alert mailers globalmailers
email-alert level warning
email-alert from
email-alert to
email-alert myhostname Haproxy
balance roundrobin
timeout connect 20000
timeout server 20000
retries 3
option httpchk OPTIONS /
acl bpm hdr_sub(host) -i
server ihshost ssl check inter 800 verify none resolvers globalresolvers


At this point, you should also have DNS records similar to these.

  • @
  • @
  • @



Was this article helpful?
0 out of 0 found this helpful