Preparing Apache Tomcat
AM examples often use Apache Tomcat (Tomcat) as the deployment container. In these examples, Tomcat is installed on
openam.example.com and listens on the default ports without a Java Security Manager enabled.
JVM start up
AM core services require a minimum JVM heap size of 1 GB, and a metadata space size of up to 256 MB. If you are evaluating AM and using the embedded DS, you require at least a 2 GB heap, as 50% of that space is allocated to DS. See "Preparing a Java Environment" for details.
CATALINA_OPTS environment variable with the appropriate tuning for your environment. For example, add the following in the
export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m"
Some versions of Internet Explorer and Microsoft Edge support the
Expires header attribute instead of the
Max-Age header attribute, which may cause SAML v2.0 and agent logout sequences to fail.
If you have set the
org.apache.catalina.STRICT_SERVLET_COMPLIANCE Tomcat property to
true, add the
org.apache.tomcat.util.http.ServerCookie.ALWAYS_ADD_EXPIRE property in the
$CATALINA_BASE/bin/setenv.sh file, to add the
Expires attribute to the headers:
export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m \ -Dorg.apache.tomcat.util.http.ServerCookie.ALWAYS_ADD_EXPIRES=true"
Slashes in Resource Names
Some AM resources have names that can contain slash characters (/), for example, in policy names, application names, and SAML v2.0 entities. These slash characters can cause unexpected behavior when running AM on Tomcat.
In development environments, a possible workaround is to configure Tomcat to allow encoded slash characters by adding the
org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true property to the
CATALINA_OPTS variable; for example:
export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m \ -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
Do not enable
org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH when running AM in production as it introduces a security risk.
For details, refer to How do I safely enable the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH setting in AM/OpenAM (All Versions)? in the ForgeRock Knowledge Base.
Set the cookie domain name value to an empty string (for host-only cookies) or to any non-top level domain (for domain cookies). For example, if you install AM on
openam.example.com, you can set the cookie domain name to
Because host-only cookies are more secure than domain cookies, you should use host-only cookies unless you have a good business case for using domain cookies.
Refer to "To Configure an Instance" to configure the cookie domain during installation.
Encoding and Security
ForgeRock recommends that you edit the Tomcat <Connector> configuration to set
URIEncoding="UTF-8". UTF-8 URI encoding ensures that URL-encoded characters in the paths of URIs are correctly decoded by the container. This is particularly useful if your applications use the AM REST APIs and some identifiers, such as usernames, contain special characters.
sslProtocol property to
TLS to disable the potentially vulnerable SSL v3.0 protocol.
<Connector> configuration elements are found in the configuration file,
/path/to/tomcat/conf/server.xml. The following excerpt shows an example <Connector> with the
sslProtocol attributes set appropriately:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" URIEncoding="UTF-8" />
When you have finished setting up Apache Tomcat, ForgeRock recommends that you enforce HTTPS connections to AM. For more information, refer to "Configuring AM's Container for HTTPS".