Preparation

Before you set up IAM, take these steps to prepare.

Prepare server to run IAM

You need to prepare a server to run IAM.

Install Node.js

IAM's strategy is to support the LTS version of Node.js. The currently supported version is found here, which can be downloaded from the official site.

Hint: To check your current Node.js version, use the following command: node --version

Decide the hostname of your server

IAM needs a fixed hostname so that all registered applications can find it. Changing the hostname after IAM configuration affects all registered applications. Before setup, please consider carefully which hostname to use for your IAM service.

Prepare Domino server to host the IAM database

IAM uses domino-db module to communicate with Domino, so a compatible version of Domino server is required.

In addition, you must:

• Configure Proton on this Domino server. IAM uses advanced data encryption features provided by Proton.
• Enable the ID vault.

Please refer to the Prerequisites section in Domino Configuration for details.

Prepare SSL certificate for IAM server

As a security service, IAM uses HTTPS for the communication channel. To support HTTPS, prepare a certificate for the IAM server.

Note: IAM only supports PEM format certificate file and private key. If your files are PKCS (.p12) format, you first need to convert the format.

The following steps show how to prepare the certificate with openssl. You can use another tool, if you prefer.

Step 1: Create a private key

Create a private key for IAM:

Example:

openssl genrsa -aes256 -out iamserver.key 2048

Note: Please enable passphrase protection on your iamserver.key PEM file. If your key file is generated without protection, openssl can be used to add passphrase protection to your key:

openssl rsa -aes256 -in iamserver.key -out rsa_encrypted_server.key

Additionally note that the IAM server supports RSA private keys in PKCS#1 format. Later versions of openssl will generate a private key in PKCS#8 format with either this header

-----BEGIN PRIVATE KEY-----

or this header if the key is encrypted as recommended.

-----BEGIN ENCRYPTED PRIVATE KEY-----

If your key starts with either of these headers, you will need to convert from PKCS#8 to PKCS#1 with the following command

openssl rsa -traditional -aes256 -in iamserver.key -out iamserver_pkcs1_enc.key

Step 2: Create a CSR (Certificate Signing Request) file

The CSR file contains IAM server information. The CSR file is provided to a Certificate Authority when you request an SSL certificate.

Create a file called iamserver.cnf that includes the following information:

[ req ]
default_bits       = 2048
distinguished_name = req_distinguished_name
req_extensions     = req_ext

[ req_distinguished_name ]
countryName                 = Country Name (2 letter code)
stateOrProvinceName         = State or Province Name (full name)
localityName               = Locality Name (eg, city)
organizationName           = Organization Name (eg, company)
commonName                 = Common Name (e.g. fully qualified host name)

[ req_ext ]
subjectAltName = @alt_names

[alt_names]
DNS.1   = iamserver.com

Please make sure IAM server hostname is in the alt_names list.

Use the following command to create the CSR file for IAM:

openssl req -new -out iamserver.csr -key iamserver.key -nodes -config iamserver.cnf

During CSR file creation, you are asked to input the passphrase of the private key and the certificate information.

Step 3: Send the CSR to Certificate Authority to get the certificate

To request the certificate, provide the CSR file to a Certificate Authority (CA). The CA will need to send you back the following certificates:

• The PEM format of the root CA certificate file if the CA is not a well-known trusted CA.
• The server certificate for IAM server (in PEM format).
• If the certificate is signed by an intermediate CA, the CA chain file with the intermediate CA(s).

If there is a chain file, copy its contents to the server certificate file to create one final certificate file. This certificate file will be deployed in IAM setup process.

The final certificate file may look like this:

-----BEGIN CERTIFICATE-----
[content of server certificate]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[content of intermediate CA certificate]
-----END CERTIFICATE-----
...

The order of certificates in certificate file doesn't matter.

Tips:

If you are using your self-created CA to sign your certificate, the following sample script demonstrates how to sign a server certificate with it.

Example:

openssl x509 -passin pass:passw0rd -req -days 365 -in iamserver.csr -CA ca.crt \
-CAkey ca.key -out iamserver.crt -CAcreateserial -CAserial ca.seq -sha256 -extfile \
<(printf "[SAN]\nsubjectAltName=DNS:iamserver.com") -extensions SAN

The extfile and extensions options are used to append subjectAltName into the certificate. Please refer to OpenSSL document for more details.

Check Outputs

As a result of the previous steps, now you have:

• A server to run IAM with:

  • Node.js installed.
  • Fixed hostname assigned.

• Certificate and private key for IAM server:

  • The PEM format IAM server certificate. (concatenate with the intermediate CA chain files if the certificate is signed by an intermediate CA).

    Note: Make sure you certificate contains a value for Subject Alternative Names extension (SAN) in the field subjectAltName. Modern browsers can consider a certificate without SAN invalid and display a security warning.

  • The private key protected by a passphrase.
  • The passphrase of the key file.

• The certificate of the root CA.

  Using an SSL certificate issued by a well-known, trusted CA is recommended. But if the SSL certificate is NOT signed from trusted CA, the certificate of the root CA will also be needed in IAM setup.

• Domino server with Proton is well configured.

• Domino ID vault is enabled.