Configuring SAML authentication on multiple Domino servers.

Copyright 2022 by Rob Kirkland. All rights reserved.

It seems that HCL has neglected to publish the full set of instructions for configuring SAML authentication between Domino HTTP servers and Microsoft ADFS. The documentation as published results in one properly configured Domino server. But if you’re setting up multiple Domino servers to host a single Web site behind a load balancer / IP sprayer (i.e., you have configured multiple servers as hosts in a Web Site document), what you’ll end up with is one server (the one on which you performed the configuration work) that properly redirects authentication requests to ADFS and other servers that cannot do so and end up prompting users for credentials themselves.

The missing steps are:

1.     Export the Service Provider certificate, created during the first Domino server’s (“Server1”) configuration, from the first Domino server’s ID file.

2.     Import the SP certificate into the ID files of the other Domino server(s) hosting the Web site.
Important note: This includes any servers not currently existing or not currently hosting the Web site, but that may do so in the future.)

NOTE: Roberto DeLaRosa of HCL Support provided me with the instructions below. If you ever find yourself receiving support from Robi, consider yourself lucky; you are in the care of a competent and resourceful individual. 

TIP: Consider composing the set config commands below in a Notepad document, then proofreading, then pasting into the Domino Command field in the Server Console.

TIP: For a better understanding of what you’re going to do below, examine Server1’s ID file and look at its Internet Certificates. The steps below will export them from Server1 and import them into Servers 2 through n. Subtip: If there are multiple Internet certificates in the export file, and you don’t want to import them all into the target server(s), consider editing the export file to remove the unwanted certificate(s).

TIP: Make backup copies of the server ID files before performing the steps below. Name the backup copies such that it is clear how they are different from other copies of the ID files. Maybe even create a readme.txt file to clarify. And then put everything, including the export ("p12") file created below, in a zip file. Finally (and most importantly), stash the zip file in a secure place and delete any unsecured copies of it or its content.

Part 1: Exporting the Certificate from Server1’s ID file

1.     Run Domino Administrator and connect to Server1, the server that properly redirects users to the ADFS Identity Provider for authentication.

2.     Open the IdP Configuration document in the idpcat.nsf

a.     Click the Certificate Management Tab

b.     Take note of the Company name including the exact case.

c.      Take note of the Certificate public hash value.

3.     Navigate to the Server, Status tab and select the Domino console. Click the “Live” button. (Alternatively, you can perform the next steps in the server's local console.)

4.     Use “set config” to set the SAMLCompanyName variable in Server1's notes.ini file. The value is the “Company Name” observed in the step above. Append upper case “CN=” to the company name (this is case sensitive). Incorrect case will cause subsequent commands to fail.

a.     Syntax:

set config SAMLCompanyName=CN=<Company name>

 Where <Company name> is the content of the Company name field in the IdP Configuration document.

b.     Example:

set config SAMLCompanyName=CN=MyAmazingCompany

5.     Use "set config" to define the Certificate public hash value (as defined in the document).
TIP: A copy and paste from the IdP Configuration document helps insure accurate transcription.

a.     set config SAMLPublicKeyHash=<hash value>

 Where <hash value> is the content of the Certificate public hash value (base 64) field of the IdP Configuration document.

b.  Example:

set config SAMLPublicKeyHash=eWJ6S2cJd+6861u+XSpmDA==

6.     Export the certificate to a file, secured with a password.

a.     Syntax:

certmgmt export saml pkcs12 file.p12 password

Where file.p12 a file name to be created.

Where password will be the password of the p12 file to be created.

b.     IMPORTANT NOTE: This process will export the private key also, which is why the export file is password protected. Please follow proper security protocols for storage, transport, and password protection of this file.

c.  Example command:

certmgmt export saml pkcs12 mykeys.p12 s3cuR1ty@!F1rsT

d.     Note: The file will be saved into Server1’s data directory.

Part 2: Importing the certificate into the other Domino servers’ ID files.

In this part we will import the p12 file created in Part 1 into the ID file(s) of Server2.

NOTE: If more than two servers will host the Web site for which you created the subject IdP Configuration, you will repeat this procedure on servers 2 through n.

NOTE: If additional servers may be added or substituted as Web Site hosts in the future, and their ID files exist now, consider importing the certificate into their ID files as well. If new but not yet registered servers will host the Web Site, consider saving the export file (and its password) somewhere secure. (See the earlier tip about making and securing a zip file.)

1.     Copy the p12 file from Server1 to the data directory of each target server (where you wish to import).

NOTE for Linux users: If a target Domino server resides on a Linux host, make sure that the p12 file is owned by the owner of the other Domino processes.

2.     Launch the Domino Console from the administrator's client. (Alternatively, open the local console on the target server.)

3.     Enter the import command using the same details as before for filename and password. NOTE: Since the file is in the server's Domino\data directory, there's no need to enter a path.

a.     Syntax:

certmgmt import pkcs12 file.p12 password

b.     Example:

Certmgmt import pkcs12 mykeys.p12 s3cuR1ty@!F1rsT

c.      Confirm that your import was successful by issuing the following command:

certmgmt show all

 The command will display the details of the certificate(s) that was/were imported.

4.     Restart the HTTP task on server2.

5.     Test SAML authentication on server2.

NOTE: If the Web servers are behind a load balancer, you my need to disable the HTTP service on all but the one Domino server being tested.

TIP: An easy way to determine which server you are connecting to is to open the homepage.nsf database. First, edit the design of the Intro page of the homepage.nsf database, adding computed text with a value of @ServerName to one of the table cells.

6.     Optional cleanup: Delete the p12 files from data directories of servers 1 through n. (But, as previously suggested, keep a copy somewhere safe if you might need to perform more imports in the future. Otherwise, you will have to create a new p12 file by performing another export at that time.)