Skip to content

HTTPS for production

Best practice for any REST API access is to secure the connection using TLS (colloquial, still referred to as SSL). This applies to the Domino REST API too. In general you have two options:

Use a Reverse Proxy

Terminate your TLS connection at a proxy. When the proxy runs on the same "machine", this is a common and accepted practice. We have outlined the steps using nginx as reference.

Use a TLS Certificate

The REST API can directly use TLS and is HTTP 1.1 and HTTP/2 compliant. You would obtain a TLS certificate from your IT security team or your favorite supplier (We like LetsEncypt, it's free) and set the configuration parameters in a json file.

  • Use the following entry to configure TLS for jks or pfx (set TLSType to the correct type):

{
  "TLSFile": "path.to.file",
  "TLSPassword": "password-in-clear-protect-this",
  "TLSType": "pfx"
}
Use the following to configure TLS for pem:

{
  "TLSFile": "path.to.file",
  "PEMCert": "path.to.crt.file",
  "TLSType": "pem"
}

Note

If you won't define a password, you must set the value of TLSPassword to "".

Tip

It's your choice which key you want to use. Main considerations are the assessment of your security team and the ease of acquisition of a specific key format in your organization.

Read the details here: configure certificate.

Caution

The Domino server task communicates with the REST API through the KeepManagementURL. It has a default value of http://localhost:8889. You can overwrite this ssetting in the notes.ini by editing (or creating if missing) the entry KeepManagementURL (case sensitive). Having configured an TLS certificate you need to make sure the entry starts with https:// and uses the host name your TLS certificate has been issued for. localhost, 127.0.0.1 or ::1 will not work. Configuring TLS doesn't change the port, so when you host, your TLS certificate is issued for, is domino.demo.com and your old entry was missing or is the default of http://localhost:8880, then your new value needs to be: https://domino.demo.com:8889 For more information, see Domino REST API task and ports.