AppDevPack Security Setup explained
Daniel Nashed 26 May 2019 06:30:22
AppDevPack Security Setup explained
Configuration of the AppDevPack with all components -- specially the new IAM component -- isn't that straight forward when you are not used to juggle with certificates often.
I had a deeper look into it, because we want to automate the configuration process for Docker deployment.
My ultimate goal would be to completely automate deployment. But not all components are scriptable today.
But let me explain the components and how they need to be glued together to make it easier for your to install and configure it.
I also have built a script that can help you to create the right certificates, described at the end of this blog post.
It is part of the IBM Docker script. But could also be used for normal deployments.
Currently you can find the script here -> https://github.com/IBM/domino-docker/blob/develop/management/manage_certs.sh.
It's still in the develop branch of the project. That link will change once we merged the last changes to the master branch.
The steps that you have to do to install and configure are well documented here --> https://doc.cwpcollaboration.com/appdevpack.
But the documentation doesn't explain in detail how all components play together from security point of view.
I hope the following description complements the official documentation and helps you setting up Proton with IAM.
You should read the official documentation first, before looking into those additional information.
-- Daniel
Overview of Components
The AppDevPack consists for the following main parts:
Proton Servertask
This is the heart of the AppDevPack and implements the new GRPC protocol.
Access to this task can be either anonymous, by client certificate or new with the IAM service with an OAUTH2 token.
Proton is a servertask which needs a keyring file with a proper certificate. The certificate needs to be issued to the DNS name of the server (for example proton.nashcom.loc).
The communication with the GRPC protocol (e.g. DQL queries) are handed by this servertask.
Proton hasn't got a well known port today. Choose any port above 1024 (the ports below are restricted ports on Linux).
I have chosen 1353 on my server. There are also examples using port 3002.
Notes Database "iam-store"
The database is used to store IAM data on the server. This database has to be created from iam-store.ntf which isn't in the Proton package but in the IAM server package.
During installation you have to copy it from the IAM server package.
The IAM Client user.id needs to have editor access to the database, because the IAM server will use the client certificate to authenticate on the Proton server and access the database via Proton.
DSAPI Filter liboauth-dsapi.so
The DSAPI filter is an extension to the HTTP task and is needed to allow authentication for additional services implemented via HTTPS ( e.g. Calendar services)
If you want to use those services you have to properly configure HTTPS (with another keyring file) to allow secure communication.
This is really a separate component which is independent from Proton.
The DSAPI filter confused me, when first looking into this. But it is a separate part of the setup with a separate access to Domino via HTTPS beside Proton access.
This DSAPI will communicate with the IAM server to verify tickets and stores tickets also in the Web credential store.
Helper Servertask oauthcfg
This servertask is needed to configure the trust store for the DSAPI filter and is just invoked for configuration.
It is executed once to configure an additional configuration and writes the credential store configuration for the DSAPI Filter.
Before you can do that, you need to configure the credential store first.
IAM Server (Node.js application)
IAM stands for Identity and Access Management. This is a standard term which is also used by different products
(see for example: https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html).
It is used to log in users and also to control access to applications.
This service is used for GRPC and also for HTTPS requests.
IAM leverages LDAPS communication for authenticating users and speaks on it's own with the Proton servertask for example to safely store the user tickets in a central Notes database iam-store.
Im most cases the user data is either in Domino Directory or in Active Directory in most of the cases. And we need a LDAPS with a proper certificate and matching name for the LDAP Server (it could be the Proton server).
IAM Client User ID
The IAM server stores it's data securely in iam-store.nsf.
Beside a client certificate for communicating with Proton, the IAM server needs a person document and Notes.ID which is stored in ID-Vault to be able to encrypt IAM data on the server.
The certificate is read from ID Vault and used for encryption.
Overview of Certificates and Keys
For secure communication all those components need to be able to communicate over SSL/TLS.
This requires Server and Client X.509 certificates. Let me describe the required certificates below.
The overview should help you to understand how all components work together from the security side.
Notes.ID for IAM Client / X.509 Client Certificate/Key
First of all you need a Notes.ID for the IAM Service. The IAM Client component of the IAM server uses a client certificate to communicate with the Proton server.
Beside the client certificate this user needs to a Notes.ID which is also stored in an ID-Vault!
The Notes.ID is used for encryption. The client certificate is used for authentication with the Proton server.
You need to import the client certificate (X.509) into the person document.
On the other side it is stored on the IAM server. The certificate is stored in PEM format and needs a password, which needs to be configured on the IAM server.
Server Certificate for Domino Server
Any Domino server accessed via HTTPS needs a proper Web Server Certificate which is stored in a keyring file.
Encrypted communication is required for HTTPS (port 443) access and also for LDAPS (Secure LDAP communication over port 636).
This could be on the same server or two different servers. In that case you would need two separate Domino keyring files with different hostnames.
Server Certificate for Proton
Proton uses the keyring file format to store the server key and certificate. It also needs a Web Server Certificate for secure communication.
The keyring file needs to contain the trusted root for their own certificates and also for the IAM Client certificate.
In the best case all your certificates are issued by the same CA. That would not require to add trusted roots and intermediate certificates into the keyring file.
Server Certificate for the IAM Server
Also the IAM server needs a Web Server certificate for secure communication.
This is a standard Web Server certificate and stored in PEM files instead of a keyring file on the Domino server side.
Client Certificate IAM Client
The IAM server needs to communicate with the Proton Servertaks.
Client certificate based authentication needs a X.509 certificate which is trusted by the Proton keyring file for the issuing CA.
The person document for the IAM Client needs to contain the Internet (X.509)Certificate.
You can manually import the file into the person document.
Summary: List of Certificates used
- Web Server Certificate (keyring) for Domino HTTPS and LDAPS
- Web Server Certificate for Proton (keyring)
- Web Server Certificate for IAM Server (PEM file)
- IAM Client Certificate (PEM password protected)
- IAM Notes ID with X.509 Client cert added to the person doc. Notes.ID must be available in ID Vault!
X.509 Certificates
In an enterprise/production environment or a internet facing service, you will have to use official certificates at least for the directly accessed components like IAM or your webserver.
The client certificate used by the IAM service only needs to be trusted by the Proton server.
For all certificates used, the corresponding other side need the CA Root and intermediate certificates from the connecting counter part in it's "local key store".
For example when the IAM server connects to Proton it has to verify the certificate of the host it connects to.
The Proton Server needs the CA's certificates to verify the ÍAM Client access.
In the best case all your certificates are coming from the same CA. This simplifies the configuration and is a best practice.
For a production environment you should consult the colleagues responsible for certificates and the internal CA.
For a test environment or a very small scale deployment, you can use your own created CA which will than be used to issue certificates for all the different components mentioned above.
The key here is that you create one CA and generate all certificates for all server and client components in IAM/Proton.
You cannot just use "self signed certificates" because there will not be a trusted root. But with openssl you can create your own local CA and issue certificates on your own.
IBM/HCL provides a simple script that generates a CA key and certificate, which is used to certify all your certificates.
The CA certificate will be your trusted root which should be stored in all your trust stores (keyring files, IAM server key-store).
Creating Certificates
There is a very basic script in AppDevPack 1.0.1. But it's not really configurable and you have to actually go into the code and change different places.
Therefore I wrote my own script to create all mentioned certificates in one step from the same CA.
The script also generates the required PEM files which can be directly imported into a keyring file via "kyrtool import all ..".
It also provides the needed CA trust certificates in the PEM file directory "ca_all.pem" which need to be imported into the IAM service.
You can also use the CA's root cert file directly to import them into your browser to void security warnings when accessing the HTTPS connections protected by those certificates.
The script will be part of the Docker deployment routines for AppDevPack later. But I want to share this script to simplify your deployments.
You just have to specify the right names and invoke the script. It will automatically create all the keys, certs and the final PEM files.
This script could also work with an external CA. In that case the script generates the keys, CSRs (certificate signing requests) and afterwards will add the certificate to the PEM file.
The PEM files generated could be imported into a keyring file in the following way.
I have not added it to the script directly, because this needs to be performed on a machine which has Notes or Domino and the kyrtool installed.
But the steps are very simple. On Linux you have to be the "notes" user and switch into the data directory.
The first command creates the keyring file. The second commant imports the key, cert and trusted roots into the keyring file.
Example: Create keyring file and import key & certs
su - notes
cd /local/notesdata
/opt/ibm/domino/bin/kyrtool create -k keyfile.kyr -p mysecretpassword
/opt/ibm/domino/bin/kyrtool import all -k keyfile.kyr -i domino_all.pem
Keys and Certificate Management Script
Let me describe the standard procedure with the automatically generated local CA.
The script can be used either stand-alone or with a configuration file. Here is the main configuration, which should be mostly self-explanatory.
There are more configuration parameters below. But those are more for special cases.
You just need to change the following settings and run the script.
It will automatically generated the needed files (see below).
# -------------------------- #
# BEGIN MAIN CONFIGURATION #
# -------------------------- #
DOMIMO_ORG="Acme"
DOMINO_SERVER="domino"
DOMINO_DNS="domino.acme.com"
PROTON_SERVER="proton"
PROTON_DNS="proton.acme.com"
IAM_SERVER="iam_server"
IAM_SERVER_DNS="iam.acme.com"
IAM_CLIENT="iam_client"
IAM_CLIENT_NAME="/O=$DOMIMO_ORG/CN=$IAM_CLIENT"
# You can choose between two different configurations
# a.) a local, simple CA should be used
# b.) a public or corporate CA should be used
USE_LOCAL_CA=yes
CA_ORG=Acme
CA_PASSWORD=domino4ever
CERTMGR_CONFIG_FILE="/local/cfg/certmgr_config"
CERTMGR_DIR=`dirname $0`/certs
# -------------------------- #
# END MAIN CONFIGURATION #
# -------------------------- #
Running the script will generate all the keys, certs and PEM files configured above.
You could also create additional certificates. But let's stay with the certs we need for Proton/IAM for this example.
The tool generates the following directories and stores all the files with corresponding names.
-- [ca] --
All CA related files (private key, certificate, serial number)
-- [key] --
All created keys for all type of certificates
-- [csr] --
Generated Certificate Signing Requests (CSR). Should be empty, because our CA automatically signs the requests and deletes them afterwards.
-- [crt] --
Certificates for all generated keys
-- [pem] --
Complete PEM files with key, certificate and Root CA cert copied into one file in the right order to be used with the kyrtool to import certificates into a keyring file.
Those files can be directly imported via "kyrtool import all".
There is one special file ca_all.pem contains the certificate either of our own Root CA or for external CAs you should copy the Root CA and intermediated certs in the right order into this file (ordered from specific to unspecific -- Root CA's at the end).
This file is added to the other PEM files automatically for your convenience if you copy it before you run the script.
-- [txt] --
Lists detailed information about the certificates.
Now that you have all the certificates you can use them in the right step of the AppDevPack documentation.
With this overview it should be a lot easier to understand the AppDevPack documentation.
Below you see the sample output from the script. The certificate expiration is configured to 10 years for the CA and also for the certificates.
This is can be configured in the configuration file or script.
--------------------------------------------
ca -> OK
--------------------------------------------
KeyLen : 4096 bit
Subject : /O=NashCom/CNÊ
Valid Until : May 15 12:12:47 2029 GMT
--------------------------------------------
--------------------------------------------
domino -> OK
--------------------------------------------
KeyLen : 4096 bit
Subject : /O=Nashcom/CN=domino
DNS NAME : domino.nashcom.loc
Valid Until : May 15 12:12:47 2029 GMT
--------------------------------------------
--------------------------------------------
iam_client -> OK
--------------------------------------------
KeyLen : 4096 bit
Subject : /O=Nashcom/CN=iam_client
Valid Until : May 15 12:12:52 2029 GMT
--------------------------------------------
--------------------------------------------
iam_server -> OK
--------------------------------------------
KeyLen : 4096 bit
Subject : /O=Nashcom/CN=iam_server
DNS NAME : iam.nashcom.loc
Valid Until : May 15 12:12:51 2029 GMT
--------------------------------------------
--------------------------------------------
proton -> OK
--------------------------------------------
KeyLen : 4096 bit
Subject : /O=Nashcom/CN=proton
DNS NAME : proton.nashcom.loc
Valid Until : May 15 12:12:50 2029 GMT
--------------------------------------------
Complete PEM files including trusted roots -> /local/certmgr/pem
Certificates issues by CA locationed here -> /local/certmgr/crt
- Comments [1]
![[HCL Domino]](../lotus-domino.gif){kind=small}
![[Domino on Linux]](../domino-linux.gif){kind=small}
![[Nash!Com]](../nashcom.gif){kind=small}
![[Daniel Nashed]](../daniel-nsh.gif){kind=small}