Preparing a Java Environment

AM software depends on a Java runtime environment. Check the output of the java -version command to make sure your version is supported according to "Java Requirements".

Important

It is important to keep your Java software up-to-date with the latest supported version. Make sure that your JAVA_HOME environment variable always points to the latest supported Java version.

The following table summarizes the high-level tasks required to configure your Java environment:

TaskResources

Prepare the JDK of your choosing for AM

The suggestions in these sections pertain to AM deployments with the following characteristics:

  • The deployment has a dedicated DS server for the Core Token Service. The host running this directory server is a high-end server with a large amount of memory and multiple CPUs.

  • The AM server is configured to use CTS-based sessions.

Configure Additional Settings for Proxy Support

If AM will make HTTP requests through a proxy server, you need to set additional JVM settings.

Tune the JVM for AM

ForgeRock provides guidance on how to tune the JVM for production, but you still need to tune it for garbage collection based on your environment.

Settings For Oracle Java Environments

When using an Oracle Java environment, set at least the following options:

-server

Use -server rather than -client.

-Xmx1g (minimum)

AM requires at least a 1 GB heap. If you are including the embedded DS, AM requires at least a 2 GB heap, as 50% of that space is allocated to DS. Higher volume and higher performance deployments require additional heap space.

-XX:MetaspaceSize=256m

Set the metaspace memory size to 256 MB.

-XX:MaxMetaspaceSize=256m

Set the maximum metaspace memory size to 256 MB.

For additional JVM tuning and security recommendations, see "Tuning JVM Settings".

Settings For IBM Java Environments

When using an IBM Java environment, set at least the following options:

-DamCryptoDescriptor.provider=IBMJCE, -DamKeyGenDescriptor.provider=IBMJCE

Use the IBM Java Cryptography Extensions.

-Xmx1g (minimum)

AM requires at least a 1 GB heap. If you are including the embedded DS, AM requires at least a 2 GB heap, as 50% of that space is allocated to DS. Higher volume and higher performance deployments require additional heap space.

Settings for OpenJDK Java Environment

When using an OpenJDK Java environment, set at least the following options.

-Xmx1024m (minimum)

AM requires at least a 1 GB heap. If you are including the embedded DS, AM requires at least a 2 GB heap, as 50% of that space is allocated to DS. Higher volume and higher performance deployments require additional heap space. Recommended: -Xmx2048m.

-XX:MetaspaceSize=256m

Set the initial metadata space size to 256 MB.

Settings for Configuring a JVM Proxy

To configure AM to make requests through a proxy server, set the following HTTP or HTTPS proxy-related options depending on the protocol configured between AM and the proxy:

-Dhttps.proxyHost

IP address or hostname of the proxy server. For example, proxy.example.com.

-Dhttps.proxyPort

Port number of the proxy server. For example, 8443.

-Dhttps.nonProxyHosts

A pipe-separated (|) list of IP addresses or hostnames that should be reached directly, bypassing the proxy configuration. For example, localhost|internal.example.com.

Use wildcards (*) at the beginning or the end of the address or hostname. For example, *.example.com or internal*.

-Dhttp.proxyHost

IP address or hostname of the proxy server. For example, proxy.example.com.

-Dhttp.proxyPort

Port number of the proxy server. For example, 8080.

-Dhttp.nonProxyHosts

A pipe-separated (|) list of IP addresses or hostnames that should be reached directly, bypassing the proxy configuration. For example, localhost|internal.example.com.

Use wildcards (*) at the beginning or the end of the address or hostname. For example, *.example.com or internal*.

Note

ForgeRock's ClientHandler code, such as the Google reCAPTCHA user self-service feature or the social authentication providers, require setting the advanced server property org.forgerock.openam.httpclienthandler.system.proxy.enabled to true to enable proxy support.

Tuning JVM Settings

This section gives some initial guidance on configuring the JVM for running AM when the deployment has a dedicated CTS token store, and AM is configured to use CTS-based sessions.

These settings provide a strong foundation to the JVM before a more detailed garbage collection tuning exercise, or as best practice configuration for production:

Heap Size Settings
JVM ParametersSuggested ValueDescription

-Xms & -Xmx

At least 1 GB (2 GB with embedded DS), in production environments at least 2 GB to 3 GB. This setting depends on the available physical memory, and on whether a 32- or 64-bit JVM is used.

-

-server

-

Ensures the server JVM is used

-XX:MetaspaceSize & -XX:MaxMetaspaceSize

Set both to 256 MB

Controls the size of the metaspace in the JVM

-Dsun.net.client.defaultReadTimeout

60000

Controls the read timeout in the Java HTTP client implementation

This applies only to the Sun/Oracle HotSpot JVM.

-Dsun.net.client.defaultConnectTimeout

High setting:

30000

(30 seconds)

Controls the connect timeout in the Java HTTP client implementation

When you have hundreds of incoming requests per second, reduce this value to avoid a huge connection queue.

This applies only to the Sun/Oracle HotSpot JVM.


Security Settings
JVM ParametersSuggested ValueDescription

-Dhttps.protocols

TLSv1.2

Controls the protocols used for outbound HTTPS connections from AM.

Specify one or more of the following values, separated by commas:

• TLSv1
• TLSv1.1
• TLSv1.2
• TLSv1.3

This setting applies only to Sun/Oracle Java environments.

-Dorg.forgerock.openam.ldap.secure.protocol.version

TLSv1.2

Controls the protocol AM uses to connect to various external resources.

Specify one or more of the following values, separated by commas:

• TLSv1
• TLSv1.1
• TLSv1.2
• TLSv1.3

Note

For -Dhttps.protocols, specify the protocol version(s) Java clients can use to connect to AM.

For -Dorg.forgerock.openam.ldap.secure.protocol.version, see Securing Network Communication for a list of external resources to which communication is affected.

Specify a single protocol if AM will only use that protocol when connecting to affected external resources. For example, a value of TLSv1.2 configures AM to only use the TLSv1.2 protocol to connect.

Specify a comma-separated list with multiple protocols if AM will use the most secure protocol supported by the external resources. For example, if you are using at least JDK 11 you could specify a value of TLSv1,TLSv1.1,TLSv1.2,TLSv1.3, which configures AM to attempt to use the TLSv1.3 protocol to connect to external configuration and user data stores. If a TLSv1.3 connection is not supported, AM attempts to use TLSv1.2 to connect, then TLSv1.1, and if still not supported, AM uses TLSv1.

Garbage Collection Settings
JVM ParametersSuggested ValueDescription

-verbose:gc

-

Verbose garbage collection reporting.

-Xlog:gc*

-Xlog:gc=info:file=$CATALINA_HOME/logs/gc-info.log

Logs detailed information about garbage collection. When using the -Xlog:gc option, you can also specify the level, and output file.

-XX:+HeapDumpOnOutOfMemoryError

-

Out of Memory errors generate a heap dump automatically.

-XX:HeapDumpPath

$CATALINA_HOME/logs/heapdump.hprof

Location of the heap dump.

-XX:+PrintClassHistogram

-

Prints a heap histogram when the JVM receives a SIGTERM signal.


Read a different version of :