This is the 2nd post in my "IAM dabbeling" sequence - as a preamble let me say upfront that I am not an administrator and no expert in the TLS/SSL arena. I am a (web) developer who wants to use OUATH2 in my Node.JS applications with Domino. That said, some experts out there might be finding easier/better ways to achieve this goal - I'm happy to learn. What I do here is to write down the path that worked for me - yours might be different/easier/quicker - feel free to comment.

With that, let's get started with the basics of setting up IAM which is: Setting up the proton task on your domino server and securing it using SSL encryption and Authorization.


First thing up - as we install the Domino appdev pack, we have to run the proton server add-in task on a linux Domino server. The current version (february 2019) is only available on Linux. This is the proton protocol task for Domino only - domino-db as the Node.js package can be run on any platform - in my case all the test node applications (proton clients) are running on MacOS.


I will not go into any details regarding the setup of a Domino server on Linux - there are other guides out there that shold help you along like here:

http://www.devinolson.net/devin/spankysplace.nsf/downloads/DOLN-AFKK4N/$File/Domino9onCentos6.pdf

Also, please do yourself a favour and use the brilliant start script of lifetime champion Daniel Nashed, you can request it here:

https://www.nashcom.de/nshweb/pages/startscript.htm

I am not using Docker containers for now, I decided that a VM running CentOS 7.5 would be sufficient for me. In case you want to use Docker, keep an eye on Daniel Nasheds Blog as well as he is heavily envolved in making these happen. Also check out the following repo from Thomas Hampel as starting point for Docker and Domino:

https://github.com/IBM/domino-docker

So let's assume you have a VM with CentOS 7.x and Domino 10.0.1 installed. You have a user for Domino that ideally is part of the SUDOs group.


My Domino Server paths are the following, please take note of yours accordingly:


Server BIN: /opt/ibm/domino/bin

Server-Files: /opt/ibm/domino/notes/latest/linux

Data-Directory: /local/proton/domiodata (yeah, I know, why use standards?!)


Make sure that your user for domino as r/w access rights in these directories and files.


I downloaded the Appdev pack to my /install directory.


Make sure that OpenSSL is working on your VM (Command line: openssl version should be giving something like: OpenSSL 1.0.2k-fips  26 Jan 2017)


Step 1: Take note of your hostnames.


My Domino server cerrtifier is: CN=Proton1/O= C3UG/C= CA

My Domino host name is: proton1.c3ug.ca which is an alias for:

My VM's hostname: proton1.fritz.box which is coming from my DHCP server (to find out your current hostname use:

hostnamectl status


on the command line. using hostnamectl set-hostname


allows you to set/change your hostname if needed.


I also added the basic alias proton1 to my hosts file in the CentOS VM to 127.0.0.1 as an additional alias as well as my Domino alias proton1.c3ug.ca


Step 2: Firewall Considerations


CentOS 7.x runs systemd firewall per default. using Webmin or other visual tools you can open up the ports needed by the various tools or do as I did and disable the VMs firewall as it is always running behind the Macs firewall plus the routers firewall. DO NOT DO THIS IN PRODUCTION - this is for dev/test purposes only !!!


To disable system3 use these commands as root:


systemctl disbale firewalld


and


systemctl stop firewalld


(to reverse that:
systemctl enable firewalld

and

systemctl start firewalld


to check the state use: systemctl status firewalld)


Step 3: Install Node.js


Now, to run the IAM server on top of the Domino server, we need to install Nodes.js. Currently (February 2019) IAM supports Nodejs V8.12.0 which can be found here:

https://nodejs.org/download/release/v8.12.0/

The link cluding the package name is:


https://nodejs.org/download/release/v8.12.0/node-v8.12.0-linux-x64.tar.gz

Then, we have to install node manually as we can not use the latest stable release. I found this pretty helpful:


Install a Package from the Node Site

One option for installing Node.js on your server is to simply get the pre-built packages from the Node.js website and install them.

You can find the Linux binary packages
here. Since CentOS 7 only comes in the 64-bit architecture, right click on the link under "Linux Binaries (.tar.gz)" labeled "64-bit". Select "Copy link address" or whatever similar option your browser provides.
On your server, change to your home directory and use the
wget utility to download the files. Paste the URL you just copied as the argument for the command:
cd ~
wget
https://nodejs.org/download/release/v8.12.0/node-v8.12.0-linux-x64.tar.gz

Note: Your version number in the URL is likely to be different than the one above. Use the address you copied from the Node.js site rather than the specific URL provided in this guide.

Next, we will extract the binary package into our system's local package hierarchy with the
tar command. The archive is packaged within a versioned directory, which we can get rid of by passing the --strip-components 1 option. We will specify the target directory of our command with the -C command:
sudo tar --strip-components 1 -xzvf node-v* -C /usr/local


This will install all of the components within the
/usr/local branch of your system.
You can verify that the installation was successful by asking Node for its version number:

node --version

v8.12.0


The installation was successful and you can now begin using Node.js on your CentOS 7 server.


This is the link where I shamlessly copied the above paragraph:


https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-a-centos-7-server

Step 4: Setup PROTON on the Domino Server


Stop your domino server.


open a command line and switch to

/opt/ibm/domino/notes/latest/linux


make sure libnotes.so is present (ls -l libnotes.so)


expand the proton-addin archive (in my case from /install)


sudo tar -xvf /install/proton-addin-.tgz
("TAB" is your friend here !)


fixup file permissons and ownership


sudo sh -v ./setup_proton.sh


start the Domino server


at the console you should see


PROTON> Build -xxxxxxxxxxxxxxxxx
PROTON> Listening on 127.0.0.1,
port 38770, INSECURE
PROTON> Note: Requested
port was 0, Actual listen port is 38770
PROTON>
Server initialized
PROTON>
Server only allows Anonymous access.

if not, issue a "load proton" command and check outputs


if necessary, add the PROTON task to the SERVERTASKS= line in the notes.ini in /local/proton/dominodata/notes.ini in my case.


The proton task should now be up and running


Step 5: Securing PROTON with SSL and Client Authentication


Step 5.1: Downloading and installing the KYR-Tool


If you ever dealt with SSL and Domino you might be familiar with the KYR-Tool. If not, this is a special tool to package SSL Certificates in a keyring file in a way that Domino can consume. This tool is not be default part of the domino server install and has to be downloaded seperately. You can find the download here:


https://www-945.ibm.com/support/fixcentral/swg/selectFixes?parent=ibm~Lotus&product=ibm/Lotus/Lotus+Domino&release=9.0.1.2&platform=All&function=fixId&fixids=KYRTool_9x_ClientServer

You will need the Linux 64 bit version and have your IBM-ID at hand :-)


the resulting file "kyrtool" must be placed in /opt/ibm/domino/bin/tools/


This position causes some issues with the scripts IBM/HCL provided to create our certificates in the next section.


Step 5.2: Creating the certificates that are needed.


In this tutorial, we will focus on self-signed SSL certificates and the scripts that are provided therefor by IBM/HCL in the appdev pack.

First, we have to create the base Certification Authority (CA) and the CRT and KEY files for the proton server and the technical user.


This is done by the script:


make_certs.sh


Of course, we have to make some changes to this script before running it - it has to be tailored to your domino server.


using nano, edit the script. Here are my changes (athe top and the  the bottom section of the file)


top:


if [[ -f ca.key || -f ca.crt ]]

then

       echo "CA already exists."

else

       # Generate CA private key

   (set -x ; openssl genrsa -passout pass:1234 -des3 -out ca.key 4096)

   # Self-Sign CA key

   (set -x ; openssl req -passin pass:1234 -new -x509 -days 365 -key ca.key -out ca.crt -subj "/O= C3UG/CN= C3UG-Test-CA" -sha256)


These changes are related to my certifiers in Domino. I would think they are not needed but I had issues importing the client certs later for the technical users without them. Might as well be only me but this worked for me.
SO PLEASE USE YOUR CERTIFIER STRINGS here accordingly !

bottom:


create_key server "/O= C3UG/CN=PROTON1" "DNS:proton1.fritz.box"

create_key app1 "/O= C3UG/CN=app1" ""

create_key app2 "/O= C3UG/CN=app2" ""


After some talks on slack with Oliver Busse, please make sure that your file access to the Domino paths is correct for the notes user. Sometimes even running the scripts using sudo gives you errors with certain files, e.g. server.key. In this case, check your permissions, delete the old stuff from a previous run and try again. Running as root is a option but you will have to chown your user right after running the scripts for the notes user or you have the next pitfall. Don't worry, running those scripts does not do anything harmfull to your environment so you can run them until the result is ok. patience is of the essence here.


This will create "server.key, server.crt, app1.crt, app1.key, app2.crt, app2.key, ca.crt and ca.key, etc.)

Step 5.3: Create the Domino Keyring file


In a great effort, Oliver Busse fixed the scripts, so download make_keyring.sh from here:


https://gist.github.com/zeromancer1972/74ddbdc655bf15616cdc1928d522730b

and copy them to /opt/ibm/domino/notes/latest/linux/


using nano, edit the kyrtool function of your make_keyring.sh file to point to your notesdata folder, in my case /local/proton/notesdata


I also recommend to rename the keyring and the stashfile names "sample1.kyr" and "sample1.sth" into something more meaningfull like your servername, in my case proton1.kyr and proton1.sth


running this script, you will end up having 2 new  files in /tmp:

- proton1.kyr

- proton1.sth


copy those files to /opt/local/proton/dominodata


Step 5.4: Setting up SSL for PROTON


Stop your domino server.


Got to /local/proton/dominodata (your data directory that is)


edit notes.ini using nano.


Add the following lines to your notes.ini if not yet there:


PROTON_LISTEN_ADDRESS=0.0.0.0

PROTON_LISTEN_PORT=3002

PROTON_SSL=1

PROTON_KEYFILE=proton1.kyr


restart the domino server, PROTON TASK should start saying secure and anonymous access only.


Step 5.5: Create technical user and import client certificate


refer to this section here:


Client authentication

Proton authenticates client application requests based on the setting of the PROTON_AUTHENTICATIONnotes.ini setting. Valid options are:

client_cert: The client certificate is mapped to a Person document in the server's directory. Access to data is calculated based on this identity. Proton must be enabled for TLS/SSL for this option.

anonymous: All requests are made as the Anonymous user identity. This name does not need to appear in the directory, but it does need to exist in database ACL. This option is available with and with out TLS/SSL being enabled.

The default behavior when the setting does not exist is to provide Anonymous access to Domino databases.







Client certificate authentication

To require that applications provide a valid client certificate set the following notes.ini variable:

PROTON_AUTHENTICATION=client_cert

With this setting enabled there are some additional administrative and client requirements.

  1. The client application must supply a valid client certificate when making domino-db requests to the Proton server on Domino. The common name in the client certificate must have a name that can found in the Domino directory. Proton performs a lookup in the Domino directory to find the person document.
  2. The Domino administrator must create a Person document in the Domino directory and perform the Import Internet Certificates Action on the Person document. This is required because the client certificate is verified against the known certificate in the Domino directory.
Image:IAM dabbeling - Post 2: setting up proton and testing

Now - a lot of people get stuck here - import the certificates by importing the app1.crt file. No need to create a *.pem or whatever.

Example using app2, please use app1 for your demo:


Create a person record for app1. Then after saving it, select the Actions Menu...


Image:IAM dabbeling - Post 2: setting up proton and testing
and select "Import Internet Certificates" ! This brings up the following dialog:


Image:IAM dabbeling - Post 2: setting up proton and testing
Select "All Files" an pick the app1.crt file !

Image:IAM dabbeling - Post 2: setting up proton and testing
use the app1.crt here !

Image:IAM dabbeling - Post 2: setting up proton and testing
keep the format as is.

Image:IAM dabbeling - Post 2: setting up proton and testing
Click "accept all"

Image:IAM dabbeling - Post 2: setting up proton and testing
Save & Close and re-check:

Image:IAM dabbeling - Post 2: setting up proton and testing
Done !



Step 5.6 Add Client Authentication to PROTON


Stop the domino server


edit notes.ini


add the following line to your Notes.ini:


PROTON_AUTHENTICATION=client_cert


restart your server.


Now, this concludes the SSL/Authentication part !



Step 6: Test your configuration


Now, let's start coding a bit.


The appdev pack comes with samples that let you test the connectivity using SSL and Authentication:


Use the domino-db Quick start sample. Here's a configuration for your domino server access using SSL and Client Authentication:


Image:IAM dabbeling - Post 2: setting up proton and testing



I am using ca.cert, app1.crt and app1.key from above and copied them into the project. Here's the source of my server-config.js code.


That concludes my first steps for me to set up PROTON on Domino !
var fs = require('fs');







var path = require('path');

const readFile = fileName => {

try {

return fs.readFileSync(path.resolve(fileName));

} catch (error) {

console.log(error);

return undefined;

}

};

const rootCertificate = readFile('./certificates/ca.crt');

const clientCertificate = readFile('./certificates/app1.crt');

const clientKey = readFile('./certificates/app1.key');

const { useServer } = require('@domino/domino-db');

const serverConfig = {

hostName: 'proton1.fritz.box', // DNS (!) Host name of your server

// See scripts to create kyr-file and ca for adoption !

connection: {

port: '3002', // Proton port on your server

secure: true,

},

credentials: {

rootCertificate,

clientCertificate,

clientKey

}

};


module.exports = serverConfig;





Heiko Voigt   |   14 February 2019 09:19:00   |    Domino  OAUTH  proton  domino-db  nodejs    |  
  |   Next Document   |   Previous Document

Comments (2)

jonas       15.02.2019 9:55:46

Impressive Job by you. I think HCL / IBM shoudl simplify this process and provide thorough examples on setting up this. If they want to attract NODE JS developers they should think about making it easier to access domino with authentication.

Heiko Voigt    http://www.sit.de    15.02.2019 14:06:51

Oh absolutely, Jonas, they are very much aware of that. Don't forget - this is still a preview feature, not finally baked.