Apache Tomcat

AM examples often use Apache Tomcat (Tomcat) as the deployment container. In these examples, Tomcat is installed on am.example.com and listens on the default ports without a Java Security Manager enabled.

JVM startup

AM core services require a minimum JVM heap size of 1 GB, and a metadata space size of up to 256 MB.

Set a CATALINA_OPTS environment variable with the appropriate tuning for your environment. For example, add the following in your setenv file:

Linux
Windows

In $CATALINA_BASE/bin/setenv.sh:

export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m"

In $CATALINA_BASE/bin/setenv.bat:

set "CATALINA_OPTS=%CATALINA_OPTS% -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m"

Some versions of Microsoft Edge support the Expires header attribute instead of the Max-Age header attribute, which may cause SAML 2.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 setenv file, to add the Expires attribute to the headers:

Linux
Windows

In $CATALINA_BASE/bin/setenv.sh:

export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m \
-Dorg.apache.tomcat.util.http.ServerCookie.ALWAYS_ADD_EXPIRES=true"

In $CATALINA_BASE/bin/setenv.bat:

set "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.

Avoid resource names that contain forward slashes.

Cookie domains

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 am.example.com, you can set the cookie domain name to example.com.

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.

You can find information on configuring the cookie domain during installation in Install an instance.

Log request times

Tomcat provides components called valves that can be configured to track access to resources. The Access Log Valve outputs information about request activity to log files for you to analyze or use when troubleshooting.

To record request times in the Access Log Valve log, configure the pattern attribute to include the following values:

%D: The time taken to send an entire request in milliseconds. This is the total processing time and may be affected by network conditions.
%F: The time taken to commit the response in milliseconds.

Example Valve element in server.xml:

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
       prefix="localhost_access_log" suffix=".txt"
       pattern="%h %l %u %t "%r" %s %b %D %F" />

You can find information about the Access Log Valve configuration in the Tomcat documentation, including the %F value.

Encoding and security

You should edit the Tomcat <Connector> configuration to set URIEncoding="UTF-8". UTF-8 URI encoding means the container can correctly decode URL-encoded characters in URI paths. This is particularly useful if your applications use the AM REST APIs and some identifiers, such as usernames, contain special characters.

You should also set the protocols property appropriately to define which protocols are supported. Make sure you don’t support any unsafe protocols such as the SSL v3.0 protocol (SSLv3).

<Connector> configuration elements are found in the configuration file, /path/to/tomcat/conf/server.xml. The following excerpt shows an example <Connector> with the URIEncoding and protocols attributes set appropriately:

<Connector port="8443" protocol="HTTP/1.1"
                  SSLEnabled="true"
                  protocols="TLSv1.2,TLSv1.3"
                  maxThreads="150"
                  scheme="https"
                  secure="true"
                  clientAuth="false"
                  URIEncoding="UTF-8" />

When you have finished setting up Apache Tomcat, you should enforce HTTPS connections to AM. Learn more in Secure connections to the AM container.

PingAM 8.0.0