Skip to content

Configure certificates

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.

About this task

The procedures guide you on obtaining and configuring certificates.

Domino REST API uses certificates for:

  • signing JWT Tokens when you use Domino REST API's login API - 0..1 certificate
  • validating JWT Tokens issued by trusted Identity Providers (IdP) - 0..n certificates
  • Securing HTTPs traffic - 0..1 certificate

Obtain certificates

For HTTPS traffic, JKS, PEM, and PFX certificate formats are supported. For public and private key pairs, RSA and EC are supported. HTTPS certificates must be accepted by your browser and HTTP tool, so get valid certificates.

To get valid certificates, use any of the following approaches:

Note

If you decided to create your own certificates, you need to distribute the custom root CA to your users which isn't something you want to do unless you have tooling like Bigfix in place. Better stick to official certs

  • For public/private key generation (used for JWT), use the Domino REST API management API/UI and let it generate a public/private key file pair and a certificate.

Configure a certificate for issuing a JWT

  • Add the following JSON to a file in keepconfig.d. The extension must be .json.
{
  "JwtUsePubPrivKey": true,
  "JwtUsePemFile": true,
  "JwtIssuer": "The issuer",
  "JwtPrivateKeyFile": "keepconfig.d/private.key.pem",
  "JwtPublicKeyFile": "keepconfig.d/public.key.pem",
  "JwtCertFile": "keepconfig.d/cert.pem",
  "JwtAlgorithm": "RSA"
}

Info

The JSON file is automatically created when you use the Domino REST API management API (Port 8889) to create the files.

Configure certificates for JWT validation

Note

PEM-formatted keys (RSA/EC) are supported.

  1. Obtain the public key from your IdP provider.
  2. Add the public key to a location where general users can't write to.
  3. Add a JSON file with the following content to keepconfig.d.
{
  "jwt": {
    "oicd": {
      "active": true,
      "algorithm": "RS256",
      "keyFile": "10-jwt.pubkey"
    }
  }
}

Configure a certificate for HTTPS

  • 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.