Sorry, folks, I had a week off but here we go again!
Get ready for some console typing action! This is all about signing certs and creating new certs that will be used for the IAM application. You will also setup the IAM service app that has to run in order to setup your apps with OAuth, LDAP and the authentication via OAuth.
In the Domino App Dev Pack unpack the archive
domino-iam-service-1.0.13.tgz
file in root’s home directory (everything covered in this part will be done as root user).
cd
mkdir domino-iam-service
cd domino-iam-service
tar xvf /install/appdevpack/domino-iam-service-1.0.13.tgz
You may use a different directory to use this app but for my example the /root folder is the one.
This archive contains different parts:
- the Node.js app which is the IAM service
- a template for a Notes database
First copy the template to your Domino data directory with
cp template/iam-store.ntf /local/notesdata
In Domino Administrator switch to the files tab, select „Template files“ and find the template. Sign the template with an appropriate ID (e.g. the server ID).
Now create a new database on the server from this template. The filename could be iam-store.nsf and the title „IAM Store“. Though you can put the database wherever you want on your server I prefer to have it in the root folder. In any case remember where you created it, we will need the full path and filename later.
To make it available via Proton we have to add it to the design catalog
load updall iam-store.nsf -e
By the way: you have to issue this command for every database you want to access later with Proton (Node.js).
The rest of the archive is dedicated to the IAM service app. You should have installed Node on your server machine in part 1 so you can now issue a
npm install
This will load all the needed modules. We will let the app alone for now and continue to set up our certificates for it.
You may experience errors during the build of the module gyp. In this case try
npm install --unsafe-perm
The next step is to run the setup procedure but before that we have to create some other certificates and keys. I prefer doing this is the common install folder we created earlier:
cd /install
First create the private key for the IAM service - you have to provide a password to protect it.
openssl genrsa -aes256 -out iamserver.key 2048
You should also encrypt the key. First provide the password you used in the step before, then create a another (the same?) password for the encrypted key.
openssl rsa -aes256 -in iamserver.key -out iamserver-encrypted.key
Now create a so called certificate signing request:
openssl req -key iamserver.key -new -sha256 -out iamserver.csr
This command will ask you several questions. You are basically free to use the default values (though you might use „real“ values here), but the real important name is the „common name“. You have to use the FQHN (hostname) of your Domino server!
This is a sample I used:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:DE
State or Province Name (full name) [Some-State]:Saxony
Locality Name (eg, city) []:Dresden
Organization Name (eg, company) [Internet Widgits Pty Ltd]:We4IT
Organizational Unit Name (eg, section) []:Development
Common Name (e.g. server FQDN or YOUR name) []:domino10.local
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
Finally, you have to use this new file to get the final certificate (a self signed cert of course):
openssl x509 -passin pass:1234 -req -days 365 -in iamserver.csr -CA ca.crt -CAkey ca.key -out iamserver.crt > -CAcreateserial -CAserial ca.seq
Replace with your password and/or change the duration to any other value than 365 days. The password used in the sample comes from the script we used to create the ca.key file from the AppDev Pack scripts.
The result is a iamserver.crt file which looks similar to this:
-----BEGIN CERTIFICATE-----
[content of server certificate]
-----END CERTIFICATE-----
For the technical user account („IAMAccessor“) we also have to create a certificate:
openssl genrsa -des3 -out iamapp.key 4096
openssl req -new -key iamapp.key -out iamapp.csr -subj "/O=Proton/CN=IAMAccessor" -sha256
Please note the „common name“ in quotes: this is a canonical name of the IAMAccessor account in backward direction and with a preceding slash!
Finally sign the request with the CA:
openssl x509 -req -in iamapp.csr -CA ca.crt -CAkey ca.key -out iamapp.crt -CAserial ca.seq
Please remember: you have to use the password „1234“ for the ca as this was created by the proton script before.
Use the iamapp.crt file to add it to the technical user account. In Domino Administrator, open the person document for „IAMAccessor“. From the actions menu also choose „Import Internet Certificate“. Select „*. All Files“ in the dialog to find it. Accept all other two dialogs. Re-open the person document and check the „Certificates, Internet Certificates“ tab.
The final preparation step is not clear for me so I’ll just be safe and copy all iamserver.* files to ./config/certs and all ca.* files to ./config/certs/ca. I guess you don’t need the *.csr files as these are only intermediate results.
cp /install/iamserver* /root/domino-iam-service/config/certs/
cp /install/app1* /root/domino-iam-service/config/certs/
cp /install/ca.* /root/domino-iam-service/config/certs/ca/
Setup the IAM Service App
Still there? Great! 
To get the service running we need to create a configuration. Run
npm run setup
The setup comes in different parts that are saved accordingly. Most of the configuration is stored encrypted, only the so called „Config issuer“ can be edited later without running through the setup process again. This totally makes sense once the hostname may change.
Admin account
Leave the name „admin“ alone and choose a password for the admin account (this is not associated to any Notes account)
Server access
Choose a password to protect the server access. You should never expose this password to a user.
Config issuer
This value expects something like
https://domino10.local:9443
the full qualified hostname (domain) under which your server will be available with a valid SSL certificate. Some users reported that also a self-signed SSL certificate will work, but I did not test it.
Please also note the port (9443). As Domino’s HTTP is already using the default SSL port of 443 we have to declare a different one here.
Port settings
Please use the port you used above for the „IAM service port“. Default is 443 but in this example we used 9443. The „Admin service port“ can be set with „8443“
SSL settings
In this section we need the crt and key files we created earlier. The official docs use a sample file set with „iam.*“ - which is wrong according to the rest of the documentation. We used „iamserver“ as the names, the answers should be adopted to it. The first file is „iamserver.key“, then „iamserver.crt“.
Storage settings (where are the certificates?)
The hostname of your machine is essential. In this example it is just „domino10.local“ (without https). For the Proton port use the port you used in your notes.ini file (in our example this is 3002).
The official docs also „unknown“ files for the Proton client itself („app3.*“). We used app1.* (see above where we copied the stuff) as I also used it in my technical Notes account. It is just used for the initial handshake with your Domino server via client certificate. The order however is different, first the setup asks for the *.crt file and then for the *.key file
Final confirmation
In the end you will be asked if everything was correctly setup and then it will save the configuration.
You can find the configuration in ./config/local.properties
As you also can see a copy was made of the old configuration (which was empty at the beginning). If you ever have to re-run the setup, remove this file and rename the backup file back to local.properties again.
Now start your IAM service app with
npm start
The script will ask for the IAM server password which currently makes it impossible to use the IAM service as a real service - you cannot provide a password along with a Node.js script which runs as a service. Hopefully there will be an update soon.
The expected output is something like this:
[21:17:54][info][cluster]: Start as a single node with 1 usable CPUs
NOTICE: a draft/experimental feature (registrationManagement) enabled, future updates to this feature will be released as MINOR releases
[21:17:54][info][initServices]: Start IAM service on port 9443
[21:17:54][info][initServices]: IAM service serves on port 9443
[21:17:54][info][initServices]: Start Admin service on port 8443
[21:17:54][info][initServices]: Admin service serves on port 8443
You are now able to access the service with a browser via
http://domino10.local:8443
and you will be rewarded with this login form:
Troubleshooting
If you experience error messages when starting the server it is most likely a connection issue to your Domino and Proton task. In this case check the SSL port 443 and the Proton port 3002 to be accessible by the script. You may have to change ports and hostnames and re-run the setup again.
Next up is part 5: LDAP