PingAM 7.5.1

Secure HTTP and LDAP connections

HTTPS and LDAPS secure connections use the transport layer security protocol (TLS). TLS depends on digital certificates (public key certificates) to share the public keys for signing and encryption. These certificates include information such as the public key, the owner of the key, and a digital signature created by the issuer of the certificate.

In client-server environments, the server provides a certificate that proves that the content it serves is as intended and hasn’t been changed by malicious users. In some environments, the client must also present its own certificate. This is called mutual TLS (mTLS).

To begin the TLS handshake, the actor receiving the certificate must know and trust the issuer of the certificate. This happens by default for certificates issued by a certificate authority (CA), but not for self-signed certificates. If you decide to use self-signed certificates, you must share them across the servers and applications that need to communicate in your environment.

Be mindful of security breaches and vulnerabilities that happen across the world, and ensure your environment isn’t using outdated, insecure protocols, such as SSL 3.0, TLS 1.0, and others.

Configure the AM container for HTTPS connections

Configure the container where AM runs for HTTPS to prevent communication over insecure HTTP. This includes HTTPS communication between AM and the following components:

  • Web and Java agents

  • Client applications

  • Any other member of the Ping Identity Platform

Configuring AM for HTTPS is only the first step. You must also configure the web or Java agent, applications, and any other member of the Ping Identity Platform for HTTPS.

HTTPS connections happen at the container level, encapsulated in the TLS protocol. This means AM itself isn’t involved in checking or sending certificates. The same is true for web and Java agents.

Some advanced AM features, however, require AM to be able to validate certificates without the mediation of the container. For more information about those features, refer to AM features that use keys.

To secure communication to AM, configure the container for HTTPS connections and install AM using the https protocol and the appropriate secure port. Follow the steps in Installation to prepare your environment and install AM.

You can also reconfigure your instances to use HTTPS. Learn more in How do I enable SSL in PingAM for an existing installation?.

To control the protocols used for outbound HTTPS connections, configure the -Dhttps.protocols JVM setting in the container where AM runs. For details, refer to Security settings.

Secure Directory Server communication

Configure AM and its connected data stores to enforce secure communication. This includes communication between AM and the following data stores:

  • Configuration store

  • Identity store

  • Application and policy stores

  • CTS and UMA stores

Configure AM to trust Directory Server certificates

Secure directory server connections check certificates stored in the truststore of the container where AM runs. This procedure assumes you are using Apache Tomcat and a DS instance. Refer to your container and directory server documentation for more information.

  1. Configure your directory server to enforce secure communication if it doesn’t already.

    For DS instances, refer to Require LDAPS in the DS documentation.

    • On the DS host, export the DS CA certificate.

      DS uses a deployment ID and password to generate a CA key pair. Learn more in Deployment IDs.

      Use the dskeymgr command to export the CA certificate:

      $ /path/to/opendj/bin/dskeymgr \
export-ca-cert \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword password \
--outputFile /path/to/ca-cert.pem

    • Copy the ca-cert.pem file to an accessible location on the AM host.

    • Import the DS certificate into the AM truststore:

      $ keytool \
-importcert \
-file /path/to/ca-cert.pem \
-keystore /path/to/openam/security/keystores/truststore

    You are now ready to configure AM to use secure connections to the directory server.

Configure secure DS connections

  1. Make a backup of your environment, as explained in Back up configurations.

  2. Ensure your stores are ready for secure connections, and that AM can trust the certificates of the directory servers. Failure to do so may cause several problems, such as the amAdmin user being unable to log in, or AM being unable to start up.

    Try the change first in test or development environments.

    Certificate hostname validation is strict. AM checks that the hostname in the LDAP server certificate matches the hostname of the directory server, and DS checks that the server it’s trying to connect to has a certificate that matches its hostname.

  3. Specify the TLS protocol(s) AM will use for outbound LDAPS connections by configuring the -Dorg.forgerock.openam.ldap.secure.protocol.version JVM setting in the container where AM runs.

    For example:

    -Dorg.forgerock.openam.ldap.secure.protocol.version=TLSv1.2,TLSv1.3

    For details, refer to Security settings.

  4. To configure identity stores:

    • In the AM admin UI, go to Realms > Realm Name > Identity Stores > Store Name > Server Settings.

    • In the LDAP Connection Mode drop-down list, choose LDAPS.

    • Click Save Changes.

    Perform these steps in every realm as necessary.

  5. To configure LDAPS for the external CTS store:

    • In the AM admin UI, go to Deployment > Servers > Server Name > CTS > External Store Configuration.

    • Enable the SSL/TLS Enabled option.

    • Click Save Changes.

  6. To configure the configuration store:

    • Go to Deployment > Servers > Server Name > Directory Configuration > Server.

    • On the Connection type drown-down list, choose SSL.

    • Click Save Changes.

    Perform these steps on every server as necessary.

  7. To configure external policy and application stores:

    • Go to Configure > Global Service > External Data Stores > Secondary Configurations > Store Name.

    • Enable the Use SSL option.

    • Click Save Changes.

    Perform these steps for each store in every realm as necessary.

  8. To configure external UMA stores:

    • Go to Deployment > Servers > Server Name > UMA > External UMA store.

    • Enable the SSL/TLS Enabled option.

    • Click Save Changes.

    Perform these steps for each store as necessary.

  9. When using clients, make LDAP calls through the LDAPS port and make sure the client has access to the store certificate.

    Otherwise, the LDAP server won’t be able to validate the connection.

    For DS stores, you should also specify the keystore file containing the store certificate, and its password. For example:

    --port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \

    Different commands and keystore types may require different options. For more information, refer to the PingDS Tools Reference.