Ensure you have the PingAccess Agent SDK for Java, Apache Maven, and Apache Tomcat. These instructions assume that you are using Apache Tomcat.

  • The servlet filter sample is installed under <AGENT_SDK_JAVA_HOME>/sample.
  • A deployed version of the servlet filter is under <AGENT_SDK_JAVA_HOME>/sample/target/agent-sample.

For the initial setup of the web application, we assume you already have Tomcat or another application server set up on the same machine hosting PingAccess. Out of the box, PingAccess generates self-signed server certificates for listeners servicing runtime ports with the hostname localhost. By default, the servlet filter sample configures the Java Agent, Java Agent API, to use strict certificate checking for communications with PingAccess. The Java Agent will not be able to communicate with PingAccess over HTTPS if it is not also on localhost because of strict hostname checking. If PingAccess already has a server certificate configured with a valid hostname other than localhost, then you can deploy the Java Agent into a container on another system.

If you cannot setup the application server on the same system as an existing PingAccess service, and that PingAccess deployment still uses the default localhost server certificate for the agent port, there is another option. You can change the default strict certificate checking in agent-sample/WEB-INF/web.xml to test. See the comments in agent-sample/WEB-INF/web.xml for more detail.

  1. In the Tomcat webapps directory, create a directory called ROOT.
  2. Copy the WEB-INF, META-INF, and assets contents from /sample/target/agent-sample/ into webapps/ROOT.

    This sample servlet filter must run as / to properly carry out the OpenID Connect (OIDC) workflow.

  3. In the Tomcat bin directory, create a script called setenv.sh (Linux) or setenv.bat (Windows) with the following contents:
    • For Linux:
      export CATALINA_OPTS="-Dlog4j.configurationFile=<PATH_TO_TOMCAT_ROOT>/webapps/ROOT/WEB-INF/logs/log4j2.xml -Dserver.log.file=<PATH_TO_TOMCAT_ROOT>/webapps/ROOT/WEB-INF/logs/server.log"
    • For Windows:
      set CATALINA_OPTS=="-Dlog4j.configurationFile=<PATH_TO_TOMCAT_ROOT>/webapps/ROOT/WEB-INF/logs/log4j2.xml -Dserver.log.file=<PATH_TO_TOMCAT_ROOT>/webapps/ROOT/WEB-INF/logs/server.log"

    The agent servlet filter logging is configured in webapps/ROOT/WEB-INF/logs/log4j2.xml and outputs to webapps/ROOT/WEB-INF/logs/server.log.

  4. If running Tomcat on Linux, execute the command chmod a+x setenv.sh to make this script executable.
  5. Configure a PingAccess agent.
  6. Configure an application and associate the new agent with it.
  7. When configuring an agent through the PingAccess administration console, it automatically exports the agent properties file. Copy the downloaded properties file to webapps/ROOT/WEB-INF/agent-config/agent.properties.
    Important:

    If Tomcat is running on Java version 7, some version 8 cipher suites are unavailable. This might lead to errors.

    To work around this issue, edit agent.properties to remove the following cipher suites from agent.ssl.ciphers:
    • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  8. Start Tomcat.
  9. Open a browser and go to http://<HOST>:<PORT>/sample.

    The values for <HOST> and <PORT> here need to match the Tomcat configuration in use.

    Note:

    If your Tomcat server is not set up to use HTTPS, ensure that any related Web Sessions do not have the Secure option enabled.