Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Security and TLS

Valves, Filters and Access Control in Tomcat

Learn the difference between Tomcat valves and servlet filters, then restrict access by IP with RemoteCIDRValve, add security headers and the CSRF prevention filter.

Every request that reaches Tomcat passes through a chain of small processing steps before your servlet sees it. Some of those steps belong to the container (valves), and some belong to your application (filters). Knowing the difference tells you where to put a rule: "only the office network may use the manager" is a valve, while "add this header to every response from my app" is usually a filter.

This lesson explains both, shows the common security valves and filters, and then builds a runnable stand-in of a CIDR access check and a filter chain so the mechanics are visible. The XML is read-only; Tomcat itself cannot run on this site.

Valves versus filters

A valve is a Tomcat-specific component declared in server.xml or context.xml. It can be attached to an Engine, a Host or a Context, and it sees the request before the web application's filters. Valves are not portable: they only work on Tomcat. A filter is part of the Servlet specification, declared in web.xml or with @WebFilter, so it travels with the WAR to any container.

flowchart LR
  C["Client"] --> E["Engine valves"]
  E --> H["Host valves"]
  H --> X["Context valves"]
  X --> F["Servlet filters"]
  F --> S["Servlet / JSP"]

A request flows through valves at each level, then through filters, and finally reaches the servlet.

Use a valve when the rule is about the server (client IP, access logging, proxy headers, error pages). Use a filter when the rule is about the application (encoding, headers, CSRF, authentication tokens).

Restricting access by address

RemoteCIDRValve allows or denies requests by client address. CIDR notation such as 10.0.0.0/8 describes a whole network. The classic use is protecting the manager application:

XML
<!-- webapps/manager/META-INF/context.xml -->
<Context antiResourceLocking="false" privileged="true">
  <Valve className="org.apache.catalina.valves.RemoteCIDRValve"
         allow="127.0.0.1/32, ::1/128, 192.168.10.0/24"/>
</Context>

Anything not matching allow gets a 403. You can use deny too; when both exist, deny is checked first, then allow. The older RemoteAddrValve takes regular expressions and is easier to get wrong, so prefer CIDR. If Tomcat sits behind a proxy the "remote address" is the proxy. Put RemoteIpValve before it so the real client address (from X-Forwarded-For) is used, and list only your proxies as internalProxies:

XML
<Valve className="org.apache.catalina.valves.RemoteIpValve"
       remoteIpHeader="X-Forwarded-For"
       protocolHeader="X-Forwarded-Proto"
       internalProxies="10\.0\.0\.\d+"/>

Trusting any client's X-Forwarded-For lets anyone fake an allowed address, so the proxy list matters.

Other useful valves

Valve What it does
AccessLogValve writes one line per request (see access logs)
ErrorReportValve formats error pages (see hardening)
RemoteIpValve restores client address and scheme behind proxies
StuckThreadDetectionValve logs threads busy longer than a threshold
SingleSignOn shares a login across web apps in one host
RewriteValve URL rewriting similar to mod_rewrite

Filters Tomcat provides

Tomcat ships ready-made filters in org.apache.catalina.filters. You enable them in web.xml (or in conf/web.xml for all apps):

XML
<filter>
  <filter-name>httpHeaderSecurity</filter-name>
  <filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
  <init-param><param-name>hstsMaxAgeSeconds</param-name><param-value>31536000</param-value></init-param>
  <init-param><param-name>antiClickJackingOption</param-name><param-value>DENY</param-value></init-param>
  <async-supported>true</async-supported>
</filter>
<filter-mapping>
  <filter-name>httpHeaderSecurity</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
  • HttpHeaderSecurityFilter adds HSTS, X-Frame-Options and X-Content-Type-Options.
  • CsrfPreventionFilter requires a per-session token on state-changing requests; pair it with response.encodeURL() or hidden fields.
  • RemoteCIDRFilter is the filter version of the valve and runs inside the application.
  • CorsFilter sets cross-origin headers; list explicit origins, never * with credentials.
  • RateLimitFilter (in recent Tomcat releases) limits requests per client in a time window.
  • ExpiresFilter sets cache headers for static files.

Stand-in: a CIDR check and a filter chain

This Java stand-in implements IPv4 CIDR matching with bit operations and then wires a tiny filter chain, so you see why ordering matters. It does not use Tomcat classes.

Java Stand-in: CIDR allow list

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The .99 address is inside the allowed /24 but is denied because deny rules are checked first, exactly as in RemoteCIDRValve.

Java Stand-in: filter chain order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice the rejected POST never reaches the servlet and never gets the header, because the CSRF filter returns early. In a real chain you should place security headers before anything that can short-circuit, or the error responses go out unprotected.

Common mistakes

  • Putting a valve in an application's context.xml that is overwritten at every deploy: keep it in conf/Catalina/localhost/<app>.xml or in server.xml.
  • Allowing X-Forwarded-For from anyone, which defeats address rules.
  • Mapping a CSRF filter only to /*.do while other URLs change data.
  • Forgetting <async-supported>true</async-supported> on a filter, which breaks async servlets that pass through it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a valve run compared with a servlet filter?

    Valves belong to the container pipeline and see the request before the application's filters.
  2. 2. In RemoteCIDRValve, which list is checked first when both exist?

    Deny rules win: an address matching deny is refused even if it is also inside an allow range.
  3. 3. Why use RemoteIpValve behind a reverse proxy?

    Without it Tomcat sees the proxy's address and http scheme for every request.
  4. 4. Which is portable to any servlet container?

    Filters are part of the Servlet specification. Valves are Tomcat specific.

Summary

  • Valves are Tomcat's container-level pipeline; filters are the portable application-level one.
  • RemoteCIDRValve restricts by network, deny first; pair it with RemoteIpValve behind proxies.
  • Tomcat includes filters for security headers, CSRF, CORS and rate limiting.
  • Order matters: a filter that returns early skips everything after it.

Next: Sessions and session persistence