Domino Administrators - What You Need to Know About the Domino Rest API Part Two

In the last article of Domino Administrators - What You Need to Know About the Domino REST API (hcl-software.com) we discussed why Domino administrators should care about the Domino REST API, showed you how to download and install it and introduced you to the components. After the install, DRAPI automatically starts running on the Domino server. However, like HTTP running on Domino, issuing “load HTTP” does not mean you have a production worthy web server. In this article we will discuss the configuration steps you will want to take to ensure complete functionality and a secure interface to your Domino applications.

Securing Ports

The Domino REST API has four ports that are accessed using HTTP. The ports and the functionality they provide are:

As with any HTTP traffic, these ports should be secured with a certificate. Unlike the default web port 80, the ports do not change when accessed using TLS. In the following diagram, external web traffic requests over HTTPs are received by a Nginx proxy and then routed to either the Domino REST API or Domino webserver. Additionally, you can see how DRAPI management console access occurs by local access over 8889.

It is important to note that these ports are separate from Domino’s HTTP engine. In fact, the Domino REST API operates without HTTP loaded on the Domino server. Currently, they are not secured by Domino’s Certificate Manager and respective TLS cache. However, you can use certificate manager to acquire a Let’s Encrypt certificate. You then export the certificate from the Certificate Store, certstore.nsf, and use it for the secure port configuration. At a high level, you take the following steps to leverage certificate manager in the certificate acquisition process and then use that certificate to secure DRAPI’s ports directly on the Domino server.

1. In Certificate Store, certstore.nsf create a TLS Credential that can be exported.

2. After the credential request has been processed and has a valid certificate, use the TLS Credential document’s [Export TLS Credentials] action button to export the certificate. For the purposes of this example, PKCS12 format is selected, and file is exported as type PFX.

3. Copy rock.pfx to the Domino\Data folder of the Domino server where DRAPI is installed. Note: The location of the certificate does not need to be the Data folder. It needs to be local to the Domino server and correctly referenced in the JSON configuration file discussed in step 4.

4. On the Domino server where DRAPI is installed, create a JSON configuration file using a text editor, i.e. tls-config.json, that contains information like the following and save to the keepconfig.d folder.

{

"TLSFile": "c:/domino/data/go.pfx",
"TLSPassword": "P@$$w0rd1352",
"TLSType": "pfx"
}

5. Using a text editor, open the server’s notes.ini

6. Update KeepManagementURL to include https and the server’s host name, for example:

                KeepManagementURL=https://rock.adventure.com:8889

7. At the Domino console issue tell restapi reload

Another option is to use an outward facing proxy, i.e. nginx. As with the above, you can use Certificate Manager to acquire the certificate that is then exported and used by the proxy, keeping in mind certificate renewals require the certificate export repeated. The following links will assist you with accomplishing this. When using an outward facing proxy where HTTPs terminates, meaning the traffic between the Domino server and the proxy uses HTTP, you will not update KeepManagementURL nor will you need a TLS JSON configuration file in the keepconfig.d folder.

Configure nginx as HTTPS proxy - single domain - HCL Domino REST API Documentation (hcltechsw.com)

Configure nginx as HTTPS proxy with subdomains - HCL Domino REST API Documentation (hcltechsw.com)

Functional Accounts

Another post installation step you will need to take is to configure the functional accounts so that you can access the Healthcheck, Management and Prometheus ports. A functional account is a non-person account needed to accomplish various tasks. Creating a functional account involves creating a json configuration file and placing it in the Domino\Data\keepconfig.d folder. This configuration file will include the user name and a secret. The DRAPI documentation includes the following default text for the Management functional account, where the user name is Doctor Notes and the secret is the hexadecimal text shown below, which is the salted value for password.

{

"identity": {
"managementAPI": {
"Doctor Notes": {
"active": true,
"secret": "E4B321EBA91B7F92D9BF5EAFA5322824FEC2287B8A6C133D7C31EFB706A2BA30:1A57478185E7AF3A98F01ECA08F0BA881DBC88BEC60AE8C6F1B1CC5CC55C11A20F676E082BF2D28BB96DB5A8CFB091C767C035B380DB4CBC7D1001EA8BE01663"
}
}
}
}

You will use this example to create your configuration file, specify a different user name if you wish. After issuing a ‘tell restapi reload’ at the Domino console, access the Management console using https://localhost:8889. Note: to login enter the user name listed in the configuration file (it is case sensitive) and the password is password.

Of course, default passwords should be changed. To obtain a new secret enter a password in the Salt this field. Pressing the Salt button will provide the new secret that you will place in your configuration file. And, remember to issue “tell restapi reload” for the new password to become active.

Configure JWT

On the Management console you will see a Create IdP Certificate button. This is used to create a permanent JWT token that can be shared across multiple Domino servers running DRAPI. Pressing the Create IdP Certificate button will generate a certificate, a public/private key pair and a json configuration file in the keepconfig.d folder. These four files can be copy pasted to the other Domino servers running DRAPI if you with to share them across the environment.

A further note regarding JWT configuration: The Domino REST API can accept JWT tokens from multiple external providers. If you have external facing Domino servers, it is recommended you configure DRAPI to have access to the provider’s public key. Steps for accomplishing this may be found here.

Auth\* - HCL Domino REST API Documentation (hcltechsw.com)

OAuth

Domino REST API is designed to consume an access token. This token can be the result of an OAuth dance or simply the result of an exchange of Domino credentials. The Domino REST API provides an IdP that does the OAuth dance.

For OAuth to work there needs to be in place the oauth.nsf database and an oauth configuration file in the keepconfig.d folder.

The oauth.nsf database is created as part of the DRAPI install. You will need to edit the database’s ACL and add the Domino server running DRAPI to the OAuthAdmin role.

Next, you will create an oauth configuration file. Copy the following text.

{
"oauth": {
"active": true,
"database": "oauth.nsf",
"url": "http://rock.adventure.com:8880",
"authCodeExpiresIn": 120,
"accessTokenExpiresIn": 3600,
"refreshTokenExpiresIn": 525600
}
}

Next, open a text based editor, i.e. Notepad, and paste the text. Save the document with a .json extension, i.e. oauth.json and place it in the keepconfig.d folder. Finally, issue tell restapi reload for the configuration update to take effect.

LocalKeepAdmins Group

For the Domino databases created as part of the DRAPI install, the LocalKeepAdmins group is added automatically to the ACL of each. To utilize this ACL entry, you will need to create a group in the Domino Directory and add those that will be DRAPI admins, meaning those that will create and update scopes and applications.

DRAPI Databases

The three databases installed as part of DRAPI will need to have their ACLs updated in order to meet your organization’s security requirements by adding your administration and server groups. In addition, it is recommended you add the Domino server where DRAPI is installed as the administration server.

For the Domino Keep Agent Scheduler, keepagents.nsf, database, the default is Reader; however, you may change this to No Access. Those that manage the run time agents, i.e. LocalKeepAdmins, will need Editor access.

The Domino Keep OAuth, oauth.nsf, database requires Default access to be Author without the Delete flag. This allows users to revoke their consents using the Admin UI.

Default access for the Domino Keep Configuration, keepconfig.nsf, database needs to be Reader.

Finally, as with any databases that you add to your Domino servers, it is recommended you sign these three databases with either the Server’s ID or your organization’s signing ID. So, using the Domino Administrator client, select keepagents.nsf, keepconfig.nsf and oauth.nsf and sign them with the respective ID file.

So, in summary, your configuration steps of the Domino REST API will include

1. Securing its HTTP traffic with a TLS certificate, and update KeepManagementURL in the notes.ini
2. Create functional accounts by creating a json configuration file in the Domino\Data\keepconfig.d folder and change the password to a custom value using the Management console
3. Create a permanent JWT token that can be shared across multiple Domino servers running DRAPI. For an external facing server, configure DRAPI to have access to the provider’s key.
4. Configure OAuth for application access by updating the ACL of the oauth.nsf database and creating an oauth configuration file
5. Create and populate the LocakKeepAdmins group
6. Update the ACLs of the DRAPI databases
7. Sign the DRAPI databases

Now that the Domino REST API is fully functional and secured, in the next blog article we will show you how to use the DRAPI Admin UI to prepare a database for REST API access by creating a schema, scope and OAuth application.