14 February 2019 Thursday
IAM dabbeling - Post 2: setting up proton and testing
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
Client certificate authentication
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...
and select "Import Internet Certificates" ! This brings up the following dialog:
Select "All Files" an pick the app1.crt file !
use the app1.crt here !
keep the format as is.
Click "accept all"
Save & Close and re-check:
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:
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 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;
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-
fixup file permissons and ownership
sudo sh -v ./setup_proton.sh
start the Domino server
at the console you should see
PROTON> Build
PROTON> Listening on 127.0.0.1,
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.
- 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.
- 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.
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...
and select "Import Internet Certificates" ! This brings up the following dialog:
Select "All Files" an pick the app1.crt file !
use the app1.crt here !
keep the format as is.
Click "accept all"
Save & Close and re-check:
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:
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
|
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.