Enabling TLS support after setup

If the server has been set up without support for TLS, enable TLS support later by completing the following tasks.

Steps

Obtain a certificate chain.

For more information about obtaining a certificate chain, see Certificate chains. To prepare a Java KeyStore JKS or PKCS #12 key store with an appropriate certificate chain and private key, use the manage-certificates tool. We also recommend that you create a trust store that the server can use.
Configure the key and trust manager providers.

For more information, see Configuring key and trust manager providers.
Configure connection handlers.

For more information, see Configuring connection handlers.

Configuring key and trust manager providers

After you have a key store, configure a key manager provider to access it.

The server is preconfigured with key manager providers, JKS and PKCS12, that you can use with JKS or PKCS #12 key stores, respectively. You can update the appropriate key manager provider in most cases to reference the key store that you plan to use. The following code provides an example.

dsconfig set-key-manager-provider-prop \
     --provider-name JKS \
     --set enabled:true \
     --set key-store-file:config/keystore \
     --set key-store-pin-file:config/keystore.pin

A similar change configures a trust manager provider to reference the appropriate trust store. The following code provides an example.

dsconfig set-trust-manager-provider-prop \
     --provider-name JKS \
     --set enabled:true \
     --set include-jvm-default-issuers:true \
     --set trust-store-file:config/truststore \
     --set trust-store-pin-file:config/truststore.pin

If all clients and servers use certificates that are signed by issuers and are included in the JVM’s default trust store, you can use the JVM-Default trust manager provider to accomplish this task.

Configuring connection handlers

After you configure the key and trust manager providers, update the connection handlers to use the key and trust manager providers.

Steps

For the LDAP connection handler, use the following command to enable StartTLS with a configuration change. By default, the LDAP connection handler accepts non-secure connections.

Example:

dsconfig set-connection-handler-prop \
  --handler-name "LDAP Connection Handler" \
  --set allow-start-tls:true \
  --set key-manager-provider:JKS \
  --set trust-manager-provider:JKS \
  --set ssl-cert-nickname:server-cert \
  --set ssl-client-auth-policy:optional

If you did not configure secure communication during setup, the LDAPS connection handler is disabled. To configure LDAPS support in this scenario, enable the connection handler and configure most of the same settings. You must set allow-start-tls to false and use-ssl to true. See the following code for an example configuration.

Example:

dsconfig set-connection-handler-prop \
  --handler-name "LDAPS Connection Handler" \
  --set enabled:true \
  --set key-manager-provider:JKS \
  --set trust-manager-provider:JKS \
  --set ssl-cert-nickname:server-cert \
  --set ssl-client-auth-policy:optional

Example:

The following example uses a similar configuration change to enable the HTTPS connection handler.

dsconfig set-connection-handler-prop \
  --handler-name "HTTPS Connection Handler" \
  --set enabled:true \
  --set listen-port:443 \
  --set key-manager-provider:JKS \
  --set trust-manager-provider:JKS \
  --set ssl-cert-nickname:server-cert

Updating the topology registry

After the server connection handlers are updated to enable TLS, update the topology registry to provide information about the new configuration.

The topology registry holds information about server instances that are part of the environment, and it helps to facilitate inter-server communication, such as replication, mirroring portions of the configuration, and the PingDirectory server’s automatic backend server-discovery functionality.

The following table details the two types of entries that require updating.

Configuration Type Update description

Server instance listener configuration

Provides information that is needed to trust the TLS certificates that instances in the topology present.
The server instance listener configuration must include the server certificate, which is defined as the certificate at the head of the chain. This version must be the multi-line, PEM-formatted representation of the certificate. You can use dsconfig to import the certificate from a file, as shown in the following example.
```
bin/dsconfig set-server-instance-listener-prop \
  --instance-name ds1 \
  --listener-name ldap-listener-mirrored-config \
  --set server-ldap-port:636 \
  --set connection-security:ssl \
  --set 'listener-certificate>/ca/ds1-cert.pem'
```

The less-than operator > in the final line indicates that the value is read from a file rather than provided directly. In addition, you might not need to enclose the property name and path within single straight quotes to prevent the shell from interpreting the less-than symbol as an attempt to redirect input.

Server instance configuration

Provides information about options for communicating with those instances.
Update the server instance configuration object to reflect the new methods that are available for communication with the instance. For example, the preferred-security property identifies the mechanism by which other instances in the topology attempt to communicate with the instance.

The following example code sets the LDAPS and HTTPS ports, indicates that StartTLS support is enabled, and instructs other instances to use SSL (LDAPS) when communicating with the instance.

dsconfig set-server-instance-prop \
  --instance-name ds1 \
  --set ldaps-port:636 \
  --set https-port:443 \
  --set preferred-security:ssl \
  --set start-tls-enabled:true