Installing the servlet filter sample
Install the servlet filter sample.
Before you begin
Ensure you have the PingAccess Agent SDK for Java, Apache Maven, and Apache Tomcat. These instructions assume that you are using Apache Tomcat.
About this task
-
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.
Steps
-
In the Tomcat
webapps
directory, create a directory calledROOT
. -
Copy the
WEB-INF
,META-INF
, andassets
contents from/sample/target/agent-sample/
intowebapps/ROOT
.This sample servlet filter must run as
/
to properly carry out the OpenID Connect (OIDC) workflow. -
In the Tomcat
bin
directory, create a script calledsetenv.sh
(Linux) orsetenv.bat
(Windows) with the following contents:Choose from:
-
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 towebapps/ROOT/WEB-INF/logs/server.log
. -
-
If running Tomcat on Linux, execute the command
chmod a+x setenv.sh
to 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 file to
webapps/ROOT/WEB-INF/agent-config/agent.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.properties
to remove the following cipher suites fromagent.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
-
-
Start Tomcat.
-
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.
If your Tomcat server is not set up to use HTTPS, ensure that any related Web Sessions do not have the Secure option enabled.