PingDirectory

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

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

  2. Configure the key and trust manager providers.

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

  3. 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. In most cases, you can update the appropriate key manager provider to reference the key store that you plan to use, as shown in the following 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, as shown in the following 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.

Caching key and trust managers

When you create key and trust manager providers, caching is enabled by default, allowing the manager providers to avoid loading key store and trust store files from disk when establishing connections to process requests.

Invalidating the cache

The manager provider reloads files from the configured key store or trust store and refreshes the cache under any of the following conditions:

  • The cached manager for the configured store has a null value.

  • The path to the cached store doesn’t match the path of the configured store.

  • The length of the cached store doesn’t match the length of the configured store.

  • The last-updated time for the cached store doesn’t match the last-updated time for the configured store.

Enabling or disabling caching (optional)

You can define whether caching is enabled by using the enable-key-manager-caching or enable-trust-manager-caching properties. Supply a value of false to disable caching, causing manager providers to load managers for each connection. Supply a value of true to re-enable caching.

To create a key manager provider with caching disabled, supply the enable-key-manager-caching property with a value of false, as shown in the following example:

dsconfig create-key-manager-provider \
    --provider-name JKS \
    --type file-based \
    --set enabled:true \
    --set key-store-file:config/keystore \
    --set key-store-type:JKS \
    --set key-store-pin-file:config/keystore.pin \
    --set enable-key-manager-caching:false

To create a trust manager provider with caching disabled, supply the enable-trust-manager-caching property with a value of false, as shown in the following example:

dsconfig create-trust-manager-provider \
    --provider-name JKS \
    --type file-based \
    --set enabled:true \
    --set trust-store-file:config/truststore \
    --set trust-store-type:JKS \
    --set enable-trust-manager-caching:false

To re-enable caching, set a value of true for the same caching property used to create the manager provider, as shown in the following example:

dsconfig set-trust-manager-provider-prop \
    --provider-name JKS \
    --set enable-trust-manager-caching:true

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 types and their update descriptions
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