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
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
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
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.
set config SAMLCompanyName=CN=<Company name>
Where <Company name> is the content of the Company name field in the IdP Configuration document.
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.
set config SAMLPublicKeyHash=eWJ6S2cJd+6861u+XSpmDA==
6. Export the certificate to a file, secured with a password.
certmgmt export saml pkcs12 file.p12 password
Where file.p12 a file name to be
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).
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.
certmgmt import pkcs12 file.p12 password
Certmgmt import pkcs12 mykeys.p12 s3cuR1ty@!F1rsT
c. Confirm that your import was successful by issuing the
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.)