Ever wanted to be able to authenticate users on your Domino Web Server using a Web Service, against a MySQL database, a text file or some other external source? Or how about changing the default Domino behaviour so that user sessions remain active for days or weeks. It’s easy and I’ll show you how using Apache Tomcat and a simple Java Servlet. I’ll then discuss a more advanced setup where you can use Apache Web Server, mod_proxy and mod_rewrite to have Apache Web Server, Apache Tomcat and Lotus Domino all responding on Port 80.
Up until R6.5x user authentication options in Domino had been very limited (in my opinion). Requiring a custom DSAPI when authentication extends beyond the Domino Directory or LDAP. And unfortunately, DSAPI programs are complex little buggers written in C. I haven’t done any serious C programming since University and I’ll happily admit that I really suck when it comes to writing C 
So in my toolkit, DSAPI just has never been an option.
We’ve (Agileware) also had experience administering a Domino Web Server which used a custom DSAPI solution, and it would crash on a regular 2 week basis, guaranteed. I will not go into the details here, but let’s just say that good C programmers must be thin on the ground 
Anyway, getting back to the topic. If you’ve got a Domino Web Server and you want to be able to authenticate it against external authorative sources, what do you do? Well with R6.53+ you can now use the humble Java method:
Session.getSessionToken();
This method simply returns a LPTA token for the current Notes Session. Until recently, this has only been accessible via the Notes C API. I believe Thomas Gunz
Steve Nikopoulos @ IBM is the guy to thank for this. Thanks Thomas! Steve!
But the LPTA token is just one component of the single sign-on puzzle. For this solution you will need to have the following components installed and configured:
- Domino Server configured for single sign-on (SSO)
- Apache Tomcat installed
- Eclipse IDE and the Tomcat plugin for coding
- (Optional - advanced configuration) Apache Web Server to proxy requests for Domino and Apache Tomcat on Port 80
Process Overview
Here’s a brief overview of the process using a Domino Website contains resources (documents, views, forms, agents etc) which have restricted access and you want to provide a alternate authentication scheme.
- Request received for a secure Domino web resource.
- Domino checks for a LPTA cookie in the request. If one is not found then Domino redirects the user to the Domino login page.
- Login page submitted with login details and posts directly to Tomcat Servlet.
- Servlet implements your custom authentication logic, for example: querying the MySQL database or calling a Web Service or even just reading a text file.
- Servlet determines if the user has passed the necessary authentication tests and determines what Domino user name to authenticate the user with.
- Servlet creates a Notes Session with the Domino server.
- Servlet sends response with the LPTA cookie and redirect to the secure Domino web resource, or to the Domino login page if authentication failed.
- If a LTPA cookie was returned, then all subsequent requests having that LPTA cookie will be authenticated and will be able to access the secure Domino web resources.
The key message here is that the Servlet will receive the login requests and process the login, returning a LTPA cookie if successful. Once the LTPA cookie is returned then that cookie can be used in all subsequent requests to gain access to secure Domino resources.
So to get started, we will need our environment configured correctly.
Configure Domino Servers for Single Sign-On (SSO)
The LTPA token is only available when a Domino Server has been configured for SSO. So you need to enable SSO for the Domino Servers you want to authenticate against. This process requires a number of steps which must be completed, so I recommend that you follow the Lotus SSO guide and use the FAQ for trouble shooting. Miss one step and it will not work!
An easy way to test if SSO has been enabled on your Domino Server is to try and access the DIIOP IOR value from the Web Server. Do this by requesting the IOR directly, for example:
http://extranet.agileware.net/diiop_ior.txt.
If you receive an error when trying to access the IOR then DIIOP is not working.
You should also be able to login to a Domino Web Server A and then using that same session to access secure web pages on Domino Web B without being prompted to re-login.
A vital step that I always miss is to correctly configure the Internet Site documents. In particular, the domain name in this document must match the domain name you will issue the IOR call too. If they do not match then Domino will not return the IOR and DIIOP will not work.
It can be a real bugger to setup SSO on Domino, but follow the instructions to the letter and you should be fine.
Take Note Of The DIIOP Port
Once you’ve got SSO and DIIOP running on your Domino Server, note down the DIIOP port. You will need this information later for your Java Servlet. For example, the default DIIOP port is not usually available and so an alternate port is used 60148.
Install Apache Tomcat
Installing Apache Tomcat is usually a pretty straight forward affair. Simply:
- Make sure a Java runtime is available on your system. You can test this by entering
java --version at the command-line. If you get an error message then you need to install Java
- Download and unpack the newest stable release from tomcat.apache.org.
- The
JAVA_HOME environment variable must be set to point to the Java directory. You can test this by entering echo $JAVA_HOME at the command-line. If nothing is displayed, then it has not been configured.
- The
CATALINA_HOME environment variable must be set to point to the Tomcat directory. You can test this by entering echo $JAVA_HOME at the command-line. If nothing is displayed, then it has not been configured.
- Start Tomcat at the command-line
tomcat/bin/startup.sh. If you get errors here, then Tomcat will not run.
- No errors? Cool. Point your Web Browser to
http://localhost:8080 you should now see the default Tomcat homepage.
- (Recommended) Setup Tomcat so that it automatically starts up on boot. This step is dependent on your OS. Here is a Apache Tomcat startup script for Linux
For more detailed instructions on how to install Tomcat on your OS, I recommend Google: how to install apache tomcat. It was great to see that Ferdy Christant blogged today about how to install Tomcat on SUSE.
Install Domino Java Classes in Tomcat (NCSO.JAR)
This is a very important step and easy to miss! To enable you to reference the Domino Java classes in Tomcat, you will need to:
- Copy the
ncso.jar file from the notesdata/domino/java directory to the /tomcat/common/lib directory.
This will enable all of your Tomcat applications to use the Domino classes.
Tip: If you upgrade the Domino server software you must copy the new NCSO.JAR file to Tomcat. DIIOP may not work with previous versions of NCSO.JAR.
Download and install the Eclipse IDE and the Tomcat Plugin
Download the latest stable version of Eclipse and download the Apache Tomcat plugin for Eclipse from sysdeo.com. Read the instructions on how to configure the Tomcat plugin.
Persistent Authentication Example
Now that we’ve got our Domino + SSO + Apache Tomcat environment all setup and working. Let’s get down to actually using it.
In this example, I explain how to authenticate a Domino user and return a LPTA cookie as a persistent cookie, as opposed to the default session cookie. The advantage here is that the user only has to login once per day and that same login is then used over that period, instead of being lost when the Web Browser is closed. The code below actually sets the cookie to expire after one month, but the Domino Server session expiry settings will take precedence.
Here’s the steps for this example:
- In Eclipse, create a new Tomcat project. Set the project references to include
NCSO.JAR and the Tomcat classes (as found in tomcat/common/lib
- In Eclipse, create a new Java Servlet in the Tomcat project and copy the Java Servlet code below
- In Domino, customise the session login form which is located in the
domcfg.nsf database. You will need to customise the login HTML form so that it posts the user login directly to the Tomcat Servlet. I’ve attached an example of the domcfg.nsf for your reference.
- Deploy your Java Servlet and updated
domcfg.nsf database
- Try to login to Domino and watch the
tomcat/logs/catalina.out for errors or authenticaftion success messages.
- If the process fails, then test your environment configuration.
Code Resources
Advanced Configuration - Using Apache Web Server To Proxy Requests
The configuration described above using just Domino and Apache Tomcat will work fine in most cases. However, if you were going to deploy this on the Internet or provide access to users from behind stricter Firewall setups, then posting requests back to Port 8080 will not be feasible. Ideally, you would want all communication to take place over Port 80 and to tightly control all external communication with Apache Tomcat. Only expose what you must and therefore control the risk of compromise.
This is where the Apache Web Server steps in and the very powerful mod_proxy. Using this configuration you can setup all requests to be posted to Port 80 and redirected to the appropriate service based on a domain name, sub-directory or some other URL pattern based on regular expressions. It’s incredily flexible and powerful.
Our existing setup processes requests like this:
Request -> Domino Web Server (Port 80)
Request -> Apache Tomcat (Port 8080)
You can see that both Port 80 and Port 8080 are exposed to the Internet.
With our new setup all requests will be processed as follows:
Request *.nsf -> Apache Web Server (Port 80) -> Domino Web Server (Port 81)
Request /servlet/ -> Apache Web Server (Port 80) -> Apache Tomcat (Port 8080)
Request [anything else] -> Apache Web Server (Port 80)
Only Port 80 is exposed to the Internet and Apache does all the work of forwarding requests to the correct service.
Tip: It’s important to point out at this time that Domino and Apache Tomcat do not have to be running on the same server for this setup to work. You can separate each service on their own individual server and thereby share the load across multiple servers. You can even have your Apache Web Server in the DMZ and all Domino and Apache Tomcat on your local network, firewalled from the Internet. Way cool!
Setting Apache Web Server To Proxy Requests
So to use this setup, you need to download and install Apache Web Server. Now if you’re using Linux, there is a good chance it has already been installed. If you’re using anything else, you’ll probably have to install it manually.
You will need to perform the following changes to your existing Domino & Apache Tomcat environment:
- Apache Web Server will listen and respond to Port 80 requests. Therefore you need to change the default HTTP Port on Domino to something else. Port 81 will do.
- Recommended, but not required. I would set your firewall rules to block requests on Port 81 and Port 8080. Do this for two reasons:
- Stop direct requests to those services and,
- So that you can verify that request proxy’ing is actually working!
Change the Domino login page so that it posts the request to the correct URL (/servlet/) and Port 80, not Port 8080.
You will also need to configure the Apache Web Server for proxy’ing. This requires the following changes to the Apache Web Server /conf/httpd.conf, enable the required modules:
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/mod_proxy.so
And then enable proxy’ing and set the rules in the Virtual Host in /etc/httpd/conf/httpd.conf:
<virtualhost *:80>
ServerAdmin root@agileware.net
DocumentRoot /var/www/html
ServerName extranet.agileware.net
ServerAlias extranet.agileware.com.au
ErrorLog logs/extranet.agileware.net-error_log
CustomLog logs/extranet.agileware.net-access_log combined
RewriteEngine on
#This rule forwards any URI requests containing /servlet to Apache Tomcat
ProxyPass /servlet http://localhost:8080/
ProxyPassReverse /servlet http://localhost:8080/
#These rules forward any URI requests containing .nsf to Domino
RewriteRule ^(.*).nsf(.*) http://extranet.agileware.net:81/$1.nsf$2 [P]
ProxyPass / http://extranet.agileware.net:81/
ProxyPassReverse / http://extranet.agileware.net:81/
</virtualhost>
You will of course need to change the Virtual Host and proxy/rewrite rules to your own domain names.
Now you’ve got a pretty powerful setup! Apache Web Server proxy’ing requests for Domino and Apache Tomcat. While you’re at it you may as well install PHP and MySQL to have a truly kick-ass do-anything Web Server.
Final Thoughts
Authentication using a Java Servlet is a pretty flexible authentication process and easily extensible. For example, you could easily change the above process so that the Domino login is exposed as a Web Service, instead of the standard Login Page. Thereby, enabling other applications to easily authenticate with Domino. Since you can write the logic in your Servlet to determine how users are authenticated, and who they are authenticated as, the mind boggles as to the possibilities here!
Using the Apache Web Server to proxy requests to Domino is also a great solution which further expands the options available to you as a Domino Web Developer. No longer are you restricted to the Domino toolkit for your web applications. Now you can employ PHP, JSP and anything else that Apache Web Server & Tomcat can support, all using the same web address and Port 80.
And finally, I welcome any feedback or enhancements to this solution. If you’ve done it a better way then please let me know
Recommended Reading
Below is a list of useful references I used to create this solution and well worth a read:
First of all, a big thanks goes to Automated Logic for this blog entry, Lotus Domino and Apache Tomcat - Single Sign On (SSO).
freetagish.net - Domino Tomcat Redirector an alternative to using Apache Web Server to proxy requests, the Redirector allows Domino and Tomcat to be integrated such that certain requests are passed to Tomcat, very cool kit.
http://www-1.ibm.com/support/docview.wss?rs=463&uid=swg27006575 This Lotus Knowledge Collection had some really useful information.
Guide to configuring Single Sign-on (SSO) (1217754) This document contains instructions about how to configure Single Sign-on (SSO) for a Lotus Domino server.
Common questions and problems with Single Sign-on (SSO) (1216978) This document describes common questions and problems you might encounter when setting up or using single sign-on (SSO) for a Lotus Domino server.
Frequently Asked Questions - Using Secure Socket Layer (SSL) with Lotus Notes/Domino (1218820) This document is intended to answer the most frequently-asked questions about SSL and the Certificate Authority (CA) Process
