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.

Enable HTTPS using the Domino Certificate Manager

If you are using Domino 14 or above and your certificates are stored in the Domino Certificate Manager, you may be able to enable HTTPS automatically. For more information, see Enable HTTPS using the Domino Certificate Manager.

To learn more about Domino Certificate Manager, see Managing TLS certificates with Certificate Manager.

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

  • TLSfile must point to private key, while the PEMCert must point to the certificate chain.
  • 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.

Example of private key and a self-signed certificate using openSSL:

Bash code:

Generate a private key

openssl genpkey -algorithm RSA -out server-key.pem

Generate a certificate signing request (CSR)

openssl req -new -key server-key.pem -out server.csr

Self-sign the certificate

openssl x509 -req -days 365 -in server.csr -signkey server-key.pem -out server-cert.pem

Generate CA certificate

openssl req -new -x509 -days 365 -key server-key.pem -out ca-cert.pem

The configuration for TLS for pem would look like:

{
  "TLSFile": “server-key.pem”,
  "PEMCert": “server-cert.pem”,
  "TLSType": "pem"
}

Read the details here: configure certificate.