Domino AppDev Pack

1.0.3

Setup guide overview

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.

  • Instructions use:

    • 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 appsdb1.jumbocloudservices.com hostname.

  • IAM service is accessible via the auth.jumbocloudservices.com hostname.

Tools and Conventions

About certificates

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.

OpenSSL

This guide shows how to use the openssl command line tool to manage SSL certificates. openssl is either pre-installed or easily installed on most Linux environments. On Windows, you can find a reference to a Windows package here.

We used this kit installed in the default directory: C:\Program Files\OpenSSL-Win64

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 administrative functions:

  1. generating a private key
  2. 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 certs 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 documentation 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 chain.crt 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

The 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.

The file 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

The 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.

Node.js

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 through the 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

  • c:\> is the Command Prompt prompt. 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 --quiet is 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.

← Design Catalog AdministrationInstallation →