Apache as a reverse proxy for IBM Domino iNotes with home server redirection

How to setup an Apache reverse proxy and IBM Domino iNotes to automatically redirect users to their Domino Mail server for secure Domino Mail access.

There are a lot of tutorials and articles describing how to configure reverse proxy software to protect the access to IBM iNotes Mails or build a HA access to Domino Servers, but none of them really shows how to configure a reverse proxy in a way that users are automatically redirected to their Domino Mail server. This article shows how an Apache Reverse Proxy can be configured to achieve this goal.

marc gaillard (marc.gaillard@de.ibm.com), IT Architect at IBM Software Groups Services for Collaboration, IBM

Marc Gaillard is an IT Architect at IBM Software Groups Services for Collaboration. He has been working with Lotus Notes since 1995 and came to IBM in 1997. His key skills are Domino Infrastructure deployment, migration, as well as IBM Domino development and in the last years also IBM SmartCloud and on premise private SmartCloud.



24 April 2013

Introduction

Setting up a Domino Server to deliver mail services in a browser is not that complex. This requires some changes in the Domino server and Internet Sites documents and the start of the HTTP Domino server task. As long as the access is limited to the intranet just setup the Lotus iNotes Redirect database on one of the servers and provide your users with the link to that database. The Redirect database handles the redirection to the correct Domino mail server by changing the URL, this is nearly transparent to the user.

If you want to make this service available over the Internet, you will certainly want to be a little more secure and not allow the Domino Server to be directly exposed to the wild, wild Internet... This can be achieved with the setup of a Reverse Proxy. It will filter and forward the request coming from the “outside” world to your internal network and send back the server response to the requesting browser. The reverse proxy rewrites the external URL to access the mail server to an internal URL which can be used to access the domino servers in the internal network . From a users perspective all communication is done between the browser and a single host.

If all user mail databases are on one server the configuration of the reverse proxy is quite straightforward. If the mail databases are dispatched on several Domino servers, you will have to use the Lotus iNotes Redirect database and the configuration is becoming more tricky. As stated before, there are excellent articles dealing with securing iNotes behind a reverse proxy or about high availability with IBM Lotus iNotes (see Resources), but no solution for a transparent and automatic redirection of mail access in a multiple-server scenario. All the user must know is one URL e.g. http://mail.acme.com, his login name and password to access his iNotes mail file.

This article will describe how to achieve this using an Apache Reverse Proxy. Additional requirements may arise to make the authentication more secure but those are not subject of this document.

The URL issue

The goal of the iNotes Redirect Database is to redirect the user to his Domino mail server. This database gets the Domino Mail server name and mail database file path information from the names.nsf. Once redirected, the browser request go directly to the iNotes Mail database on the user's Domino mail server.

There are three types of redirection in the iNotes Redirect Database. The one that fits to our need and allows the redirection to the user's mail server is 'MailServer'. When the user is redirected, the common name of its Domino mail server will be appended to the path portion of the URL.

If his mail database is /mail/user2.nsf on server domino2, then the path generated by the redirect database will be /domino2/mail/user2.nsf.

Figure 1. iNotes with Redirect database behind a reverse proxy
Architecture: iNotes with Redirect database and two Domino Mail server, behind a reverse proxy.

In the figure (Figure 1) above, the user enters the external URL http://mail.acme.com/iwaredir.nsf. This must be translated to the internal URL http://domino1 .acme.com/iwaredir.nsf. The user is redirected to the login page. The Redirect database uses the Notes user name to lookup the Domino mail server name and mail file path and builds the corresponding URL : http://mail.acme.com/domino2 /mail/user2.nsf which is to be translated internally to http://domino2 .acme.com/mail/user2.nsf by the reverse proxy.

As long as the URL adheres this patterns, the reverse proxy configured with the correct directives will be able to redirect all requests to the corresponding Domino server.

The issue is that the iNotes mail database generates subsequent URLs disregarding the server name part of the originating URL. For example for accessing /iNotes/Forms85.nsf/...

For these URLs, the reverse proxy must be told how to build the correct URL for the internal links.

The solution is to catch the URL returned by the iNotes Redirect database as response to the first user request, that contains the domino server common name and let the reverse proxy save the information in a cookie. This cookie will then be used by the Reverse Proxy for URLs that do not contain the server name to build the URL correctly.

The Setup

The test setup consists of three Domino servers version 8.5.3. The Lotus iNotes Redirect database is on one of them, all servers are in the same Domino Domain.
In addition to that, an Apache Reverse proxy server 2.4.2 on a virtual machine running ubuntu 12.04.1.
External URL that the user will access is: https://mail.acme.com
Internal URLs for the Domino servers are: domino1.acme.com, domino2.acme.com, domino3.acme.com
The iNotes Redirect database is on Domino1/Acme. Domino2/Acme, Domino3/Acme are the two other Domino Mail servers.

Setting up the Domino environment:

— Define a Web SSO Configuration Document and Domino Web SSO key or import a WebSphere LTPA Key, give that document a name and under Participating Servers select all the Domino Mail servers that should share the key:

Figure 2. Domino Web SSO document
Configuring Domino Web SSO.

— Define an Internet Sites document of type Web, configure the Basics tab as needed and on the Domino Web Engine Tab under HTTP Sessions set the session authentication to Multiple Servers (SSO) and in the field Web SSO Configuration, select the document you have created in the previous step:

Figure 3. Domino Internet Sites document
Configuring Domino Internet Sites.

On the configuration tab, set /iwaredir.nsf as Home URL. This is the database that is open by default, when no other path is specified.

— Create the IBM iNotes Redirect database from the iwaredir.ntf database template. Name it as defined in the Internet Sites above. e.g. iwaredir.nsf

Click on setup and then on Server Settings:

Figure 4. iNotes Redirect database configuration
Configuring the iNotes Redirect database.

Select MailServer as Redirection Type, enter your Domino name and the reverse proxy URL, that the users will use.

Go to Application Setup and apply the ACL changes as specified.

Save the document.

Installation and setup of the Apache 2.4.2 Reverse Proxy

Assuming you have already installed ubuntu server 12.04.1, you can then install Apache:

Listing 1. Install apache on ubuntu
apt-add-repository ppa:ptn107/apache 
apt-get update 
apt-get install apache2

Once installed your Apache server should already be up and running. Directing a browser to your server's URL should give you the following result:

Figure 5. iNotes Redirect database configuration
Configuring the iNotes Redirect database.

In addition to the modules enabled by default, the following Apache server modules must be enabled:
In a command line interface, use the following command: a2enmod
and select the following modules to enable : proxy, proxy_http, rewrite, ssl

Remark: In the test setup it is assumed that the connection Browser → Reverse Proxy is secured with SSL and the connection Reverse Proxy → Domino is not. For the test environment a self signed server certificate using OpenSSL was generated. In a productive environment a verified certificate must be used.

Apache ReverseProxy Configuration

The configuration of the Apache server can be made in several configuration files, all located in /etc/apache2.

To keep it simple, the server is configured in /etc/apache/site-available.

Go to that directory and open the 000-default.conf configuration for edit and within the section <VirtualHost *:80> … </VirtualHost> comment out the line: #DocumentRoot /var/www
There is no need for that as we only want to configure a ReverseProxy server.

Add the following line at the end of the section:
Redirect / https://mail.acme.com
This will redirect all non-SSL HTTP requests to HTTPs.
Save and close this file.

Verify that this site configuration is enabled:
→ a2ensite
Enable it if necessary.

iNotes specific configuration

Create a site configuration document (e.g. inotes-redirect.conf) in the directory ./sites-available, save it and enable it using:
a2ensite

All subsequent configurations will be made in this file. The following is the basic configuration file for the iNotes configuration. The rules defined there should be easy to understand. See Apache documentation for further information.

Listing 2. Apache basic configuration file for iNotes
ProxyRequests off

SSLSessionCache "shmcb:logs/ssl_scache(512000)"
SSLSessionCacheTimeout  300

<VirtualHost *:443>

# Site info
ServerName mail.acme.com
ServerAdmin administrator@acme.com

# Rewrite engine on
RewriteEngine On
RewriteOptions Inherit 
				
# Enable SSL		
SSLEngine On
SSLProxyEngine On
SSLCertificateFile /etc/apache2/mail.acme.com.crt
SSLCertificateKeyFile /etc/apache2/mail.acme.com.key

# Log filenames
ErrorLog ${APACHE_LOG_DIR}/error-inotes-redirect
CustomLog ${APACHE_LOG_DIR}/access-inotes-redirect common

LogLevel warn

# The iNotes Specific configurations comes after this line


</VirtualHost>

Simple configuration:

This simple configuration works well and it is easier to understand the rules used for reverse proxying iNotes with this example. A more secure configuration is described in the next section.

Listing 3. Simple configuration
# Rule 1: Read domino server name from first access to the mail
# directory, save it to the cookie and redirect to the mail server
RewriteCond %{REQUEST_URI} ^/(.*)/mail
RewriteRule /(.*)/mail/(.*) http://$1.acme.com/mail/$2 [P,CO=iNotesServer:$1:.acme.com]

# Rule 2: If cookie is set, use it to rewrite rules for iNotes generated
# URLs for the server defined in the cookie iNotesServer
RewriteCond %{REQUEST_URI} ^/
RewriteCond %{HTTP_COOKIE} ^.*iNotesServer=([^;]+)
RewriteRule /(.*) http://%1.acme.com/$1 [P]

# Rule 3: if no cookie set, on first access on the iNotes iwaredir.nsf
RewriteCond %{REQUEST_URI} ^/
RewriteRule /(.*) http://domino1.acme.com/$1 [P]

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#

ProxyPassReverse /domino1/mail/ http://domino1.acme.com/mail/
ProxyPassReverse /domino2/mail/ http://domino2.acme.com/mail/
ProxyPassReverse /domino3/mail/ http://domino3.acme.com/mail/
		
ProxyPassReverse / http://domino1.acme.com/
ProxyPassReverse / http://domino2.acme.com/
ProxyPassReverse / http://domino3.acme.com/

The first access is done by requesting the iNotes Redirect database. This will be caught by Rule 3 and the request is redirected to the server domino1.acme.com. Every request that is not caught by the two other rules will be handled by this rule.

When the user is logged on and assuming his mail file is located on the server Domino2 the iNotes Redirect database will return an URL following the pattern: https://mail.acme.com/ domino2/mail/user2.nsf?OpenDatabase. This URL request is caught by Rule 1. This rule does two things: it takes the server name that is between the hostname part and the /mail/ expression and saves this in a cookie named iNotesServer. In addition, it redirects the request internally to the corresponding Domino mail server:
e.g. the URL request https://mail.acme.com/domino2/mail/usermail.nsf?OpenDatabase is redirected to http://domino2.acme.com/mail/usermail.nsf?OpenDatabase

Now, as said before, the iNotes database generates URLs that do not contain the domino server name. Calls to the Forms85.nsf database are an example: https://mail.acme.com/iNotes/Forms85.nsf/... This is where Rule 2 is used. One of the conditions for this rule is to look for the availability of the cookie iNotesServer saved before and use its content — the name of the Domino server — to build the internal URL based on the external URL. The URL https://mail.acme.com/iNotes/Forms85.nsf/.... is redirected to http://domino2.acme.com/iNotes/Forms85.nsf/....

This rule is used from now on for this session, whenever a URL request is made, if the cookie is set to a Domino server name and if Rule 1 doesn't apply.

Note that the order of the rules is essential for this configuration to work.

The ProxyPassReverse directives are necessary to make sure that the URL in the HTTP response header sent back are correctly adjusted. Unfortunately the names of all participating Domino mail servers must be hard coded here.

This configuration has some drawbacks. The cookie remains until the session is closed. If another user uses the same session to check his mail, his first attempt to access the iNotes Redirect database will be directed to the server defined in the cookie. In addition, requests may be done to every databases on the domino servers accessed. These are passed through Rule 3 if no cookie is set or through Rule 2 if it is set. These drawbacks are solved in the advanced configuration described thereafter.

Advanced configuration:

Listing 4. Advanced configuration
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#
# Rule 0 : If Cookie is set and user logs out, remove the cookie
RewriteCond %{HTTP_COOKIE} ^.*iNotesServer=.*
RewriteCond %{QUERY_STRING} ^Logout
RewriteRule ^/.* - [CO=iNotesServer:domino1:.acme.com:1]
		
# Rule 1 : Read domino server name from first access to the mail
# directory, save it to the cookie and redirect to the mail server
RewriteCond %{REQUEST_URI} ^/(.*)/mail
RewriteRule /(.*)/mail/(.*) http://$1.acme.com/mail/$2 [P,CO=iNotesServer:$1:.acme.com]

# Rule 2 : If cookie is set, use it to rewrite rules for iNotes generated
# URLs and non mail DBs for the server defined in the cookie iNotesServer
RewriteCond %{REQUEST_URI} ^/favicon.ico [OR]
RewriteCond %{REQUEST_URI} ^/domjs [OR]
RewriteCond %{REQUEST_URI} ^/domjava [OR]
RewriteCond %{REQUEST_URI} ^/domcfg.nsf [OR]
RewriteCond %{REQUEST_URI} ^/iNotes [OR]
RewriteCond %{REQUEST_URI} ^/icons [OR]
RewriteCond %{REQUEST_URI} ^/iwaredir.nsf [OR]
RewriteCond %{REQUEST_URI} ^/names.nsf [OR]
RewriteCond %{REQUEST_URI} ^/mail [OR]
RewriteCond %{REQUEST_URI} ^/archive [OR]
RewriteCond %{REQUEST_URI} ^/download [OR]
RewriteCond %{REQUEST_URI} ^/dwa(.*)
RewriteCond %{HTTP_COOKIE} ^.*iNotesServer=([^;]+)
RewriteRule /(.*) http://%1.acme.com/$1 [P,L]

# Rule 3 :  if no cookie set, on first access on the iNotes iwaredir.nsf
RewriteCond %{REQUEST_URI} ^/favicon.ico [OR]
RewriteCond %{REQUEST_URI} ^/domcfg.nsf [OR]
RewriteCond %{REQUEST_URI} ^/iwaredir.nsf [OR]
RewriteCond %{REQUEST_URI} ^/names.nsf
RewriteRule /(.*) http://domino1.acme.com/$1 [P,L]

# Rule 4 : everything else should be redirected to the original link
RewriteCond %{REQUEST_URI} ^/
RewriteRule / http://domino1.acme.com/ [P]

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#

ProxyPassReverse /domino1/mail/ http://domino1.acme.com/mail/
ProxyPassReverse /domino2/mail/ http://domino2.acme.com/mail/
ProxyPassReverse /domino3/mail/ http://domino3.acme.com/mail/
	
ProxyPassReverse / http://domino1.acme.com/
ProxyPassReverse / http://domino2.acme.com/
ProxyPassReverse / http://domino3.acme.com/

The Apache ReverseProxy can be configured to restrict the access to only the iNotes applications. This is what this configuration does.

Rule 4 redirects every request that is not caught by the other rules to the root path '/' on the server domino1. This will be the first access request if https://mail.acme.com is used by the user to access his mail. In the test setup the iwaredir.nsf database will be opened as default homepage if no other URL is defined.
The result of this rule is the following redirection:
https://domino1.acme.com/ → http://domino1.acme.com/iwaredir.nsf
also an attempt to access a database not specified in the configuration will end in the same redirection.
E.g. https://mail.acme.com/someotherDB.nsf → https://domino1.acme.com/ → http://domino1.acme.com/iwaredir.nsf This way, no other Domino database than the ones that are defined in this configuration may be accessed.

Rule 3 handles the requests before our cookie is set. Only the URL patterns defined in the conditions are allowed. This is when accessing the iNotes Redirect database before the cookie is set.

Rule 2 restricts the access to the iNotes mail service allowing only URLs with patterns defined in the condition and when the cookie is set.

Rule 1 is the same as in the simple configuration. It sets the cookie iNotesServer and redirect the request to the Domino mail server.

If the user logs out, the cookie iNotesServer still remains until the end of the browser session. If another user wants to log on to his mail server, the rule 2 will catch his request and try to open the iNotes Redirect database on the mail server defined in the cookie. If the database is located there, this will be just fine. If not, there will be an error message. One solution is to remove the condition catching the iwaredir.nsf in Rule 2, but to circumvent this, it is preferable to define Rule 0 which catches the URL containing the pattern 'Logout' and checks for the availability of the cookie iNotesServer. Unfortunately, it is not possible to directly delete a cookie using a RewriteRule directive, so if the cookie is available, it resets it to the server Domino1 and sets its lifetime to 1 minute. If an other user logs in from the same browser, either the cookie has already been deleted by the browser or the request to the iNotes Redirect database is redirected to the server Domino1, which is the server where the iNotes Redirect database is located.

Conclusion

This concludes the installation and configuration of an Apache server as a Reverse Proxy . The way it is configured is easily portable and can be applied to other proxy servers, even if it can be directly applied to Apache on other operating systems – It was tested also on Apache installed on a Windows Server. The way configuration files are organized and modules are enabled or disabled is somehow different, but the content of the configuration file is the same.

With a few more configuration changes, Domino servers in cluster may be configured behind the IBM iNotes Redirect database. See references below.
Last but not least, it is assumed, that the Apache Reverse proxy is well secured and placed behind a well configured Firewall.

Appendix A: Complete Apache configuration file

Listing 5. Complete Apache configuration file
ProxyRequests off

SSLSessionCache "shmcb:logs/ssl_scache(512000)"
SSLSessionCacheTimeout  300

<VirtualHost *:443>

# Site info
ServerName mail.acme.com
ServerAdmin administrator@acme.com

# Rewrite engine on
RewriteEngine On
RewriteOptions Inherit 
				
# Enable SSL		
SSLEngine On
SSLProxyEngine On
SSLCertificateFile /etc/apache2/mail.acme.com.crt
SSLCertificateKeyFile /etc/apache2/mail.acme.com.key

# Log filenames
ErrorLog ${APACHE_LOG_DIR}/error-inotes-redirect
CustomLog ${APACHE_LOG_DIR}/access-inotes-redirect common

LogLevel warn

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#
# Rule 0 : If Cookie is set and user logs out, remove the cookie
RewriteCond %{HTTP_COOKIE} ^.*iNotesServer=.*
RewriteCond %{QUERY_STRING} ^Logout
RewriteRule ^/.* - [CO=iNotesServer:domino1:.acme.com:1]

# Rule 1 : Read domino server name from first access to the mail directory,
# save it to the cookie and redirect to the mail server
RewriteCond %{REQUEST_URI} ^/(.*)/mail
RewriteRule /(.*)/mail/(.*) http://$1.acme.com/mail/$2 [P,CO=iNotesServer:$1:.acme.com]

# Rule 2 : If cookie is set, use it to rewrite rules for iNotes generated URLs
# and non mail DBs for the server definde in the cookie iNotesServer
RewriteCond %{REQUEST_URI} ^/favicon.ico [OR]
RewriteCond %{REQUEST_URI} ^/domjs [OR]
RewriteCond %{REQUEST_URI} ^/domjava [OR]
RewriteCond %{REQUEST_URI} ^/domcfg.nsf [OR]
RewriteCond %{REQUEST_URI} ^/iNotes [OR]
RewriteCond %{REQUEST_URI} ^/icons [OR]
RewriteCond %{REQUEST_URI} ^/iwaredir.nsf [OR]
RewriteCond %{REQUEST_URI} ^/names.nsf [OR]
RewriteCond %{REQUEST_URI} ^/mail [OR]
RewriteCond %{REQUEST_URI} ^/archive [OR]
RewriteCond %{REQUEST_URI} ^/download [OR]
RewriteCond %{REQUEST_URI} ^/dwa(.*)
RewriteCond %{HTTP_COOKIE} ^.*iNotesServer=([^;]+)
RewriteRule /(.*) http://%1.acme.com/$1 [P,L]

# Rule 3 :  if no cookie set -> on first access on the iNotes iwaredir.nsf
RewriteCond %{REQUEST_URI} ^/favicon.ico [OR]
RewriteCond %{REQUEST_URI} ^/domcfg.nsf [OR]
RewriteCond %{REQUEST_URI} ^/iwaredir.nsf [OR]
RewriteCond %{REQUEST_URI} ^/names.nsf
RewriteRule /(.*) http://domino1.acme.com/$1 [P,L]

# Rule 4 : everything else should be redirected to the original link
RewriteCond %{REQUEST_URI} ^/
RewriteRule / http://domino1.acme.com/ [P]

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#
ProxyPassReverse /domino1/mail/ http://domino1.acme.com/mail/
ProxyPassReverse /domino2/mail/ http://domino2.acme.com/mail/
ProxyPassReverse /domino3/mail/ http://domino3.acme.com/mail/
		
ProxyPassReverse / http://domino1.acme.com/
ProxyPassReverse / http://domino2.acme.com/
ProxyPassReverse / http://domino3.acme.com/

</VirtualHost>

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=877631
ArticleTitle=Apache as a reverse proxy for IBM Domino iNotes with home server redirection
publish-date=04242013