Domino, Proton, IAM, OAuth - Part 4: IAM service

Monday, March 4, 2019 at 8:51 PM UTC

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! Wink

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






Latest comments to this post

Alex wrote on 31.07.2019, 15:55

Hi! 

Can you answer what is certificate must be in OAUTH2_DSAPI_KEYRING=<path to certificate or certificate bundle>?

https://doc.cwpcollaboration.com/appdevpack/docs/en/oauth-dsapi.html

I can't to  setup oauth-dsapi

Thanks

 Link to this comment
Oliver Busse wrote on 20.03.2019, 17:21

Hallo Volker,

danke für den Hinweis - da hatte sich ein &nbsp; (#160) eingeschlichen.

 Link to this comment
Volker Jürgensen wrote on 20.03.2019, 17:17

Hallo Oliver,

ich habe deine Zusammenfassung nachvollzogen, dabei trat diese Kleinigkeit auf: 

Diesen Befehl habe ich per Copy/Paste übernommen:

openssl req -new -key iamapp.key -out iamapp.csr -subj "/O=Proton/CN=IAMAccessor" -sha256

Dabei wurde das Leerzeichen vor dem -sha256 als Sonderzeichen übernommen, nicht erkennbar.

Der Effekt war ein falscher CN, erkennbar an einem merkwürdigen Icon im Notes Client. Nachdem ich das "Leerzeichen" ersetzt hatte, klappte alles vorzüglich.

 Link to this comment

Leave a comment right here