You can configure Domino to connect to services that use custom certificates that are external to the Domino cluster. In addition to public services like AWS S3, you might want to use private services in your security domain that are secured with custom certificates or a custom certificate authority.
The following are examples of private services:
Domino recommends that you add certificates for private services to the installation configuration file (
domino.yml) as described in this topic. This ensures that Domino propagates the certificates throughout the system and maintains them, even when you upgrade Domino.
Domino checks for
domino-custom-certificates ConfigMap in the Kubernetes cluster’s
This ConfigMap must have a key named
bundle with plaintext data of a certificate bundle in PEM format.
If the bundle exists, then Domino uses certificates from this bundle to connect to the external services.
Domino supports the following certificate types:
- Custom Certificate Authority (CA)
Certificates that certify the other certificates issued under this authority.
- Self-signed certificates
Certificates that do not have a reference to the authority signing them.
The bundle is formatted as a series of concatenated certificates in PEM format. You must have the line breaks around the lines:
The bundle must contain all the certificates that you would typically use to connect to the private services, including intermediate and root certificates.
Domino includes public certificates, such as DigiCert root certificates, by default so you do not have to include them. Duplicate certificates will not cause any issues.
For user executions, all Domino certificates, including public and customer-provided, will be stored in
If you must use custom certificates in a user session, such as to connect to internal Git servers from a Workspace command line, manually reference the certificates in
The following are some ways that you can do this:
Copy the certs from
/etc/ssl/certsin a compute environment pre-run script.
Add a Java truststore option such as:
-Djavax.net.ssl.trustStore=/etc/ssl/certs/domino-custom/cacerts.p12 -Djavax.net.ssl.trustStoreType=PKCS12 -Djavax.net.ssl.trustStorePassword=changeme
Add application-specific configurations such as setting the
GIT_SSL_CAINFOvariable for Git or passing the
--cacertoption for Curl.
You can also set these options at runtime or modify the relevant configuration files in the compute environment.
During Domino installation, you can add the contents of PEM bundle to the
domino.yml configuration file with the top-level key
The following is an example:
... custom_certificates: | -----BEGIN CERTIFICATE----- MIICKzCCAbGgAwIBAgIKe3G2gla4EnycqDAKBggqhkjOPQQDAzBaMQswCQYDVQQG EwJVUzETMBEGA1UECxMKZW1TaWduIFBLSTEUMBIGA1UEChMLZU11ZGhyYSBJbmMx IDAeBgNVBAMTF2VtU2lnbiBFQ0MgUm9vdCBDQSAtIEMzMB4XDTE4MDIxODE4MzAw MFoXDTQzMDIxODE4MzAwMFowWjELMAkGA1UEBhMCVVMxEzARBgNVBAsTCmVtU2ln biBQS0kxFDASBgNVBAoTC2VNdWRocmEgSW5jMSAwHgYDVQQDExdlbVNpZ24gRUND IFJvb3QgQ0EgLSBDMzB2MBAGByqGSM49AgEGBSuBBAAiA2IABP2lYa57JhAd6bci MK4G9IGzsUJxlTm801Ljr6/58pc1kjZGDoeVjbk5Wum739D+yAdBPLtVb4Ojavti sIGJAnB9SMVK4+kiVCJNk7tCDK93nCOmfddhEc5lx/h//vXyqaNCMEAwHQYDVR0O BBYEFPtaSNCAIEDyqOkAB2kZd6fmw/TPMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB Af8EBTADAQH/MAoGCCqGSM49BAMDA2gAMGUCMQC02C8Cif22TGK6Q04ThHK1rt0c 3ta13FaPWEBaLd4gTCKDypOofu4SQMfWh0/434UCMBwUZOR8loMRnLDRWmFLpg9J 0wD8ofzkpf9/rdcw0Md3f76BB1UwUCAU9Vc4CqgxUQ== -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIICTjCCAdOgAwIBAgIKPPYHqWhwDtqLhDAKBggqhkjOPQQDAzBrMQswCQYDVQQG EwJJTjETMBEGA1UECxMKZW1TaWduIFBLSTElMCMGA1UEChMcZU11ZGhyYSBUZWNo bm9sb2dpZXMgTGltaXRlZDEgMB4GA1UEAxMXZW1TaWduIEVDQyBSb290IENBIC0g RzMwHhcNMTgwMjE4MTgzMDAwWhcNNDMwMjE4MTgzMDAwWjBrMQswCQYDVQQGEwJJ TjETMBEGA1UECxMKZW1TaWduIFBLSTElMCMGA1UEChMcZU11ZGhyYSBUZWNobm9s b2dpZXMgTGltaXRlZDEgMB4GA1UEAxMXZW1TaWduIEVDQyBSb290IENBIC0gRzMw djAQBgcqhkjOPQIBBgUrgQQAIgNiAAQjpQy4LRL1KPOxst3iAhKAnjlfSU2fySU0 WXTsuwYc58Byr+iuL+FBVIcUqEqy6HyC5ltqtdyzdc6LBtCGI79G1Y4PPwT01xyS fvalY8L1X44uT6EYGQIrMgqCZH0Wk9GjQjBAMB0GA1UdDgQWBBR8XQKEE9TMipuB zhccLikenEhjQjAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAKBggq hkjOPQQDAwNpADBmAjEAvvNhzwIQHWSVB7gYboiFBS+DCBeQyh+KTOgNG3qxrdWB CUfvO6wIBHxcmbHtRwfSAjEAnbpV/KlK6O3t5nYBQnvI+GDZjVGLVTv7jHvrZQnD +JbNR6iC8hZVdyR+EhCVBCyj -----END CERTIFICATE-----
The installer copies the contents of the custom certificates into the
After Domino is installed and running, you can recreate the
domino-custom-certificates ConfigMap to update it.
To do this, run the following commands:
kubectl delete configmap domino-custom-certificates kubectl create configmap domino-custom-certificates --from-file=bundle
bundle is the new certificate bundle in concatenated PEM format.
To apply the new certificate bundle, restart the Domino services that use custom certificates.
Delete a pod to restart a service:
kubectl delete pod -n <namespace> <pod name>
Find the pods and services that use custom certificates. Update the
namespacein each command to match the one used in your Domino installation.
kubectl get pods -n <namespace> -ojson | jq -r '.items | select(.spec.volumes? | select(.configMap.name == "domino-generated-certificates")) | .metadata.name'
When upgrading a Domino deployment to a new version, you can use the
custom_certificates key in
domino.yml to provide a new certificate bundle.
If the key is not yet specified, the installer will do the following:
domino-custom-certificatesbundle will continue to be used, and can still be updated independently of the installer.
If there are no existing
domino-custom-certificatesConfigMap, but the legacy
domino-executor-certificatesConfigMap exists, it will be copied and upgraded to the new format/name.