---
title: Installing the servlet filter sample
description: Install the servlet filter sample.
component: pingaccess
version: 9.1
page_id: pingaccess:agents_and_integrations:pa_installing_the_servlet_filter_sample
canonical_url: https://docs.pingidentity.com/pingaccess/9.1/agents_and_integrations/pa_installing_the_servlet_filter_sample.html
llms_txt: https://docs.pingidentity.com/pingaccess/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: February 6, 2023
section_ids:
  before-you-begin: Before you begin
  about-this-task: About this task
  steps: Steps
  choose-from: Choose from:
---

# 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

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) *(tooltip: \<div class="paragraph">
   \<p>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.\</p>
   \</div>)* workflow.

3. In the Tomcat `bin` directory, create a script called `setenv.sh` (Linux) or `setenv.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 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`.

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

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