Configure certificates

Caution

The KeepManagementURL setting in your notes.ini is the URL needed for the Domino REST API Domino task to talk to the Java side of Domino REST API. By default, this is set to http. If you have updated your security to https, you must update this URL. For more information, see Domino REST API task.

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 PTX 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:

• Use Let's Encrypt with either Domino's cert manager or a proxy, such as Nginx.
• Ask your infrastructure or networking team (if you have one) for valid certificates.
• Create your own certificates using OpenSSL.

Note

You need to distribute the custom root CA to your users (Let's Encrypt preferred).

• 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 (JKS, PEM, PFX):

{
  "TLSFile": "path.to.file",
  "TLSPassword": "password-in-clear-protect-this",
  "TLSType": "pfx"
}

Tip

It's recommended to use the Domino certificate option or a proxy for HTTPS termination.