Access Management 7.2.2

Secure HTTP and LDAP connections

Both HTTPS and LDAPS secure connections are based on the transport layer security protocol (TLS), which depends on digital certificates (also called public key certificates).

Digital certificates are for sharing public keys used for signing and encryption, and they include information such as the public key, the owner of such 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 has not been modified by malicious users. In some environments, however, the client is also required to present its own certificate; this is what is called mutual TLS (or mTLS).

In order 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 never for self-signed certificates. This means that, if you decide to have 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 is not 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 web/Java agents, and AM and your applications, or AM and any other member of the ForgeRock Identity Platform.

Note that configuring AM for HTTPS is the first step; you need to also configure the web/Java agent, your applications, and any other member of the ForgeRock Identity Platform for HTTPS, too.

HTTPS connections happen at container level, encapsulated in the TLS protocol. This means AM itself is not 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, see AM features that use keys.

To secure communications 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, see Security Settings

Secure Directory Server communication

Configure AM and the identity and data stores that connect to it to enforce secure communication, either using LDAPS or StartTLS. This includes communication between AM and the CTS store, between AM and the application stores, and between AM and the identity 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 stores to enforce secure communication, if they do not already.

    For DS instances, see Require LDAPS in the DS documentation.

    DS 7 or later is configured to require secure connections by default; therefore, you might have already configured some of your stores to use secure connections during the AM installation process.

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

Secure Directory Server communication

  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 is 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, see 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 on 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 on 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, ensure you make LDAP calls through the LDAPS port and that the client has access to the store certificate.

    Otherwise, the LDAP server will not 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 \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \

    Different commands may require different options. Different keystore types, too. For more information, see the Directory Services Tools Reference .