Install the servlet filter sample.
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
checking in agent-sample/WEB-INF/web.xml to
test. See the comments in
agent-sample/WEB-INF/web.xml for more detail.
- In the Tomcat webapps directory, create a directory called ROOT.
Copy the WEB-INF, META-INF, and
assetscontents from /sample/target/agent-sample/ into webapps/ROOT.
This sample servlet filter must run as / to properly carry out the
OpenID Connect (OIDC)workflow. OpenID Connect (OIDC) OIDC An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.
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.
- For Linux:
If running Tomcat on Linux, execute the command
chmod a+x setenv.shto make this script executable.
- Configure a PingAccess agent.
- Configure an application and associate the new agent with it.
When configuring an agent through the PingAccess administration console, it
automatically exports the agent properties file. Copy the downloaded properties
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.propertiesto remove the following cipher suites from
- Start Tomcat.
Open a browser and go to
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.