This guide describes how to configure a Domino server to be used with the AppDev Pack. It describes how to configure the following AppDev Pack components:
- proton: the Domino server add-in task that provides service to Node.js applications.
- IAM: the Domino server Identity and Access Management service which is implemented as Node.js application.
The instructions assume that this is your first Domino server and that you are setting up Domino for the first time. A more experienced Domino Administrator may choose to use their existing Domino domain and use:
- An existing ID vault configuration on another Domino server
- An existing Domino directory for users
This guide is arranged in a linear fashion. When you follow the instructions for one of the steps it is expected that you have completed all previous steps.
Prerequisites and Assumptions
Domino server is installed with a minimal default configuration.
Domino AppDev Pack is installed and not configured.
User administration is performed in the Domino directory.
Your Organization does not manage a Certificate Authority (CA) for issuing SSL certificates. This setup document shows how to run your own Internal certificate authority for services that are not accessed from a browser.
Your Organization wants to use a well-known Certificate Authority for IAM and related Node.js applications so users do not see "Invalid Certificate Authority" warnings while using a browser. For the purposes of this document we will use a Let's Encrypt certificate.
All components will be hosted on the same machine, including Domino with ID vault and LDAP services, IAM, Proton, and non-shared credential store.
- HCL Domino Server - Release 11.0
- HCL Domino Administrator - Release 11.0
- Domino AppDev Pack - Release 1.0.3
Domino server is accessible via the
IAM service is accessible via the
Tools and Conventions
Many of the components in the Domino AppDev Pack use TLS/SSL certificates for authentication and privacy. In this model configuration of the Domino AppDev Pack we use two certificate authorities.
One certificate authority is used for all internal components. We include instructions to create a certificate authority which signs client and server certificates for internal use. This is the "Internal CA".
A second certificate authority is used for all external facing components. We will call this the "Well Known CA". The main benefit of a well known CA is that browsers and other systems have an out-of-the-box trust with well known CAs. Let's Encrypt is an example of a well known CA which provides free server certificates for publicly accessible servers.
Every organization that deploys applications should decide the certificate authorities to use for server and client certificates. The model configuration we describe uses two different CAs because this configuration is more complex and perhaps more realistic.
This guide shows how to use the
openssl command line tool to manage SSL
openssl is either pre-installed or easily installed on most
Linux environments. On Windows, you can find a reference to a Windows package
We used this
in the default directory:
On Windows you may need to update your system
PATH variable to include the
OpenSSL program directory. For example:
c:\>set PATH=%PATH%;c:\Program Files\OpenSSL-Win64\bin c:\>openssl version OpenSSL 1.1.1d 10 Sep 2019
The OpenSSL team provides online documentation here.
Internal certificate authority
For this guide we use the
certs directory to store all
certificates managed by the Internal CA. Managing a certificate authority can
be a complicated administration function. It involves two separate
- generating a private key
- generating a signature
Some organizations split these two functions under different administration domains. For simplicity, this guide combines the two functions so they are performed by the same administrator.
All files that hold private keys and signed certificates live in the
directory, as referenced in this guide.
c:\>mkdir \certs c:\>cd \certs c:\certs>
Let's Encrypt server certificates
For this guide we will use Let's Encrypt server certificates for our web accessible services. The details for obtaining the server certificate is outside the scope of this guide.
We used the getssl tool on a publicly
accessible Linux server. The Let's Encrypt
lists this tool, and others, that you can use. We copied the
signed server certificates to the Windows machine into the
c:\letsencrypt-certs directory. For example:
Directory of c:\letsencrypt-certs\auth.jumbocloudservices.com 12/02/2019 07:41 AM <DIR> . 12/02/2019 07:41 AM <DIR> .. 12/02/2019 07:41 AM 2,293 auth.jumbocloudservices.com.crt 12/02/2019 07:41 AM 1,635 auth.jumbocloudservices.com.csr 12/02/2019 07:41 AM 3,243 auth.jumbocloudservices.com.key 12/02/2019 07:41 AM 1,648 chain.crt 12/02/2019 07:41 AM 3,941 fullchain.crt 12/02/2019 07:41 AM 2,881 getssl.cfg 6 File(s) 15,641 bytes
Let's Encrypt root certificates
Web browsers generally have good support for Let's Encrypt server certificates because they trust the signers of the server certificates and the browser vendors build this trust into the browser installation.
We need to manually build the trust chain for Let's Encrypt so we can provide it to non-browser components. We used this Let's Encrypt page to build the trust chain. The general steps are:
Determine the signer of your server certificate:
c:\letsencrypt-certs>openssl x509 -noout -subject -issuer -in auth.jumbocloudservices.com\auth.jumbocloudservices.com.crt subject=CN = auth.jumbocloudservices.com issuer=C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3
The getssl tool provides the signer's certificate
Let's Encrypt Authority X3 as
in the same directory. Use a similar command to find the signer of this certificate:
c:\letsencrypt-certs>openssl x509 -noout -subject -issuer -in auth.jumbocloudservices.com\chain.crt subject=C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3 issuer=O = Digital Signature Trust Co., CN = DST Root CA X3
DST Root CA X3 certificate can be downloaded from this Let's Encrypt page:
c:\letsencrypt-certs>openssl x509 -noout -subject -issuer -in trustid-x3-root.crt subject=O = Digital Signature Trust Co., CN = DST Root CA X3 issuer=O = Digital Signature Trust Co., CN = DST Root CA X3
Combine the two certificates in this order into one file:
c:\letsencrypt-certs>copy auth.jumbocloudservices.com\chain.crt+trustid-x3-root.crt rootchain.crt auth.jumbocloudservices.com\chain.crt trustid-x3-root.crt 1 file(s) copied.
rootchain.crt now contains the certificate chain for trusting the Let's Encrypt certificate. Use
the following command to verify that the chain correctly builds trust for the server certificate:
c:\letsencrypt-certs>openssl verify -purpose sslserver -CAfile rootchain.crt auth.jumbocloudservices.com\auth.jumbocloudservices.com.crt auth.jumbocloudservices.com\auth.jumbocloudservices.com.crt: OK
OK reports that the
auth server certificate is trusted according to the
rootchain.crt chain of certificates.
The guide shows where to use the
rootchain.crt file in a later section.
The IAM service and the domino-db Node.js module currently support Node.js v10. Download Node.js for your platform from here and install with the default options.
The Node.js team provides developer-focused online documentation here.
This guide uses the NPM tool, which comes with a Node.js installation. The NPM team provides online documentation here.
About the examples
When possible, this guide shows how to complete a task using the command line. All the examples are written for Windows.
We tested the examples using the Windows
Command Prompt. They should also work if run
Windows PowerShell. They can be converted to their Linux equivalents, generally by changing file paths.
The following command describes the important aspects about the examples in this guide. This is only an example of a command that is shown later in this guide. The purpose of showing it now is to show how to read the examples.
c:\>openssl s_client -connect appsdb1.jumbocloudservices.com:3003 --quiet -CAfile c:\certs\internalca.crt depth=1 O = Jumbo Cloud Services, CN = Internal Certificate Authority verify return:1 depth=0 O = Jumbo Cloud Servers, CN = appsdb1 verify return:1 write:errno=0
Command Promptprompt. It shows the current directory, which is
c:\, when you're executing this command. We use different directories to keep different parts of the configuration separate and we consistently refer to the same directories in the guide. You may use different directories and file names, but you will need to make adjustments consistently as you progress through the guide.
openssl s_client -connect appsdb1.jumbocloudservices.com:3003 --quietis the command that is being executed. Some commands can be long and you will need to scroll to view or copy the complete command. We describe the most important parts of the commands, but not everything. When possible we refer to external documentation.
The remainder of the example is output generated by the given command.