Apache Tomcat ships with sensible defaults, and keeping it secure is mostly about the configuration changes you make later: keep the default servlet read-only, keep AJP off the network, and keep the Manager application internal with strong credentials. This guide covers the Tomcat-specific controls that decide whether a servlet container is a hardened runtime or an easy foothold: the Manager and Host Manager roles, connectors and AJP, realms and credential storage, valves for logging and access control, and the patching rhythm the Apache Tomcat security pages demand. Settings and defaults are taken from the Tomcat 10.1 documentation; the same elements exist in the 9.0 and 11.0 branches, but confirm defaults in the documentation for your branch. Application-level Java and Spring controls are covered separately in the Java and Spring Security Guide. It is for platform engineers, middleware administrators and application security teams who run Tomcat directly, embedded in Spring Boot, or inside vendor products.
This is an independent guide from NHI Mgmt Group, based on the Apache Tomcat project's public documentation as of November 2026. It is not sponsored or reviewed by the Apache Tomcat project. Product features change, so confirm settings against the Apache Tomcat project's current documentation.
Key takeaways
- Keep the secure defaults. Leave the default servlet read-only (readonly at its default of true) and avoid file-based session persistence unless you need it.
- The Manager application is a deployment console, so treat it as privileged access. manager-script and manager-jmx cannot be protected against CSRF, and the JMX proxy is described by the project as a root-like interface.
- AJP is cleartext and trusted by design. Keep it bound to loopback (the default), keep secretRequired="true", or remove the AJP connector if no reverse proxy uses it.
- Realms store passwords in cleartext unless you add a CredentialHandler. Wrap every realm in a LockOutRealm and hash entries in tomcat-users.xml, or move users to LDAP or SSO.
- Tomcat releases security fixes almost monthly. Track the branch's security page and apply Tomcat security updates promptly.
How identity and access work in Apache Tomcat
Tomcat implements container-managed security from the Jakarta Servlet specification. A web application declares <security-constraint>, <login-config> and roles in its web.xml; Tomcat authenticates the user through an authenticator (BASIC, FORM, DIGEST, CLIENT-CERT or SPNEGO) and checks the user's roles against a Realm, which is the user and role store. Realms are configured in server.xml at Engine, Host or Context level.
| Realm | Store | Production use | Hardening notes |
|---|---|---|---|
| UserDatabaseRealm | conf/tomcat-users.xml loaded via JNDI | Small, static environments only | Add a CredentialHandler so passwords are hashed; restrict file permissions |
| DataSourceRealm | JDBC tables | Yes | Dedicated read-only database account; hash passwords; keep Tomcat on a current release |
| JNDIRealm | LDAP directory | Yes, most common in enterprises | Use bind mode (default); useStartTls defaults to false, so enable it or use an LDAPS URL; keep Tomcat on a current release |
| LockOutRealm | Wraps other realms | Always | Defaults: failureCount 5, lockOutTime 300 seconds, cacheSize 1000 |
Three identity facts drive most of the hardening work:
- Cleartext by default: the Realm how-to states that all standard realms store passwords in cleartext unless a
<CredentialHandler>is nested in the Realm. UseSecretKeyCredentialHandlerwithPBKDF2WithHmacSHA512and generate entries withbin/digest.sh. DIGEST authentication is the exception: it requires a single unsalted MD5 iteration, which is a reason not to use DIGEST. - Add lockout to every realm: account lockout comes from the LockOutRealm, not the realms themselves. The shipped
server.xmlwraps the UserDatabaseRealm in a LockOutRealm; keep it, and add it around any realm you introduce. Lockout matching on user names is controlled by thecaseSensitiveattribute (default false). - Session cookies are credentials: the security how-to notes a session cookie for an authenticated user is nearly as valuable as the password. BASIC and FORM send credentials in cleartext, so authenticate and stay on TLS for the whole session, and use a
CookieProcessorwithsameSiteCookies="strict"on administrative contexts.
For most organisations the better pattern is to keep Tomcat's own realms for the Manager only (or remove them entirely) and authenticate application users at an SSO layer, either in the application through OIDC or SAML or at a reverse proxy. See the LDAP Security Deep Dive Guide.
Admin roles and privileged access
The Manager web application (/manager) deploys, undeploys, starts and stops applications, so anyone with a Manager role can run arbitrary code as the Tomcat user by deploying a WAR. Tomcat ships with no users assigned to any Manager role, which makes the Manager inaccessible until someone edits tomcat-users.xml.
| Role | Grants | CSRF protection | Guidance |
|---|---|---|---|
| manager-gui | HTML interface at /manager/html | Yes, per-page random token | Human administrators only, behind VPN or bastion |
| manager-script | Text interface /manager/text/* and status page | No | CI/CD deployment identity only; never combined with manager-gui |
| manager-jmx | JMX proxy /manager/jmxproxy and status page | No | Avoid; the project calls the JMX proxy a root-like administrative interface |
| manager-status | Server Status page only | Not applicable (read only) | Monitoring, but prefer an application health endpoint |
| admin-gui / admin-script | Host Manager (virtual host creation) | GUI only | Remove the Host Manager unless you create hosts dynamically |
- Remove what you do not use: delete the manager, host-manager, examples, docs and default ROOT applications from production instances (see the baseline below).
- Restrict by network: if the Manager stays, its
META-INF/context.xmlshould carry aRemoteCIDRValvewithallowlimited to loopback or the management subnet (the documentation example is127.0.0.0/8,::1/128). Never widen it to.*. - Separate the roles: the Manager how-to says never to grant manager-script or manager-jmx to a user who also has manager-gui, because a browser session with those roles is exposed to CSRF from any other site visited.
- Prefer immutable deployment: for fixed deployments the security how-to recommends
autoDeploy="false"anddeployOnStartup="false"on the Host, anddeployXML="false"where untrusted applications share the host. Deploying through the pipeline to the file system or a container image removes the need for the Manager altogether. - JMX: the project treats JMX access as equivalent to local root. Bind any JMX listener to an internal address, use strong passwords and filter the port. Monitor JMX access at the network layer.
Treat Manager accounts and the OS account that owns CATALINA_BASE as privileged identities: vault their credentials and record their use. See the Privileged Access Management Guide.
Integrations, API tokens and service accounts
Tomcat itself holds a surprising number of machine credentials, and they usually sit in plain files under conf/:
- JNDI DataSource passwords:
<Resource>elements inserver.xmlorcontext.xmloften carry database passwords in cleartext. Inject them from a secrets manager at start-up (environment variables or a property source that the pipeline renders), keepconf/readable only by root and the tomcat group, and give each application its own database account. - Keystores: TLS keystore and truststore passwords appear in the
<SSLHostConfig><Certificate>element. Rotate certificates on a schedule and alert on expiry; see the Certificate Expiry Outages and 47-Day TLS Certificates Guide. - The AJP secret: the
secretattribute on the AJP connector is a shared credential with the front-end proxy. It travels in cleartext and is visible to anyone who can watch the traffic, so it only protects a loopback or trusted-segment link. - JNDIRealm bind account:
connectionNameandconnectionPasswordidentify a directory service account. Make it a search-only account and avoid comparison mode, which the documentation calls generally undesirable because the account then needs permission to read passwords. - Deployment identity: a CI/CD job that deploys through
/manager/textuses a manager-script user with BASIC authentication. Give each pipeline its own user, store the password in the CI secret store, restrict it by source address with RemoteCIDRValve and rotate it. - Clustering: session replication should run only on a trusted network with the
EncryptInterceptor.
An inventory of these credentials per instance (owner, location, rotation date) is the single most useful identity control for a Tomcat estate. See the Secrets Management Guide.
Connectors, AJP and reverse proxies
Connectors define what Tomcat listens on. The default HTTP/1.1 connector listens on port 8080 without TLS on all addresses. Remove every connector you do not use and set address explicitly on the rest.
| Setting | Default (10.1) | Hardened value | Why |
|---|---|---|---|
AJP address | Loopback | Loopback or a dedicated interface | AJP is cleartext and trusts proxy-supplied attributes |
AJP secretRequired | true | true, with a long random secret | Connector will not start without a secret |
AJP allowedRequestAttributesPattern | null (unknown attributes rejected with 403) | Leave unset unless a proxy needs a named attribute | Accepting only named attributes keeps the connector tightly scoped |
xpoweredBy | false | false | Header reveals version and JVM |
server | Not set | Not set or a neutral value | Avoid banner disclosure |
allowTrace | false | false | Debug only |
maxPostSize / maxPartCount | 2 MiB / 50 | Lowest value the application tolerates | Resource exhaustion |
allowBackslash, encodedSolidusHandling | Secure defaults | Leave at defaults | Non-default values behind a proxy can bypass proxy constraints |
discardFacades | true | true | Prevents request data leaking between requests |
Behind a reverse proxy, the security how-to warns that path parameters such as /..;a=b/ are stripped by the servlet specification and can bypass constraints enforced at the proxy; with Apache httpd mod_proxy use mapping=servlet. Secure Tomcat as if the proxy were not there. If you use RemoteIpValve so logs show the real client address, set internalProxies to your proxy addresses only, and make sure the first proxy strips any X-Forwarded-* headers sent by clients, otherwise callers can spoof their address and scheme (and defeat a RemoteCIDRValve). Only set secure="true" and scheme="https" on a connector that genuinely sits behind TLS termination. See the Proxies and Forward vs Reverse Proxy Security Guide.
Logging and detection
The AccessLogValve is configured by default in server.xml. Extend the pattern beyond common so investigations have what they need: %{X-Forwarded-For}i or requestAttributesEnabled="true" with RemoteIpValve, %{User-Agent}i, processing time (%D or %{ms}T) and the authenticated user (%u). The JsonAccessLogValve writes each request as a JSON object, which is easier to ship to a SIEM.
| Signal | Where | What it can indicate | ATT&CK |
|---|---|---|---|
Requests to /manager/html, /manager/text/deploy or /host-manager from unexpected sources | Access log | Manager brute force or unauthorised deployment | T1110 Brute Force, T1078 Valid Accounts |
| HTTP 401 bursts followed by 200 on Manager paths; LockOutRealm warnings | Access log, catalina log | Password guessing that succeeded | T1110 |
PUT requests, especially with Content-Range, or new .jsp files appearing | Access log, file integrity monitoring on webapps/ and work/ | Unauthorised file upload through the default servlet | T1190, T1505.003 Web Shell |
| New WAR or exploded directory outside the release process | catalina log, FIM | Malicious deployment | T1505.003 |
Tomcat JVM spawning sh, bash, cmd.exe or powershell.exe | EDR or auditd | Code execution through a web shell or deserialisation | T1059 Command and Scripting Interpreter |
| Connections to 8009 or JMX ports from outside the proxy tier | Firewall, NetFlow | AJP or JMX exposure being probed | T1190 |
Measure that the controls hold:
- Patch latency: days from a Tomcat release containing an Important fix to production rollout (target under 14 days, faster for fixes the project rates Critical).
- Branch currency: percentage of instances on a supported branch and on the latest point release.
- Default application exposure: count of instances where
/manager,/examplesor/docsanswer from outside the management network (target zero). - Credential hygiene: percentage of instances with hashed realm passwords and no cleartext DataSource passwords in
conf/. - Configuration drift: number of instances failing the hardened baseline check (readonly, listings, AJP, shutdown port, ErrorReportValve).
Retention and forwarding are covered in the CIS Control 8 Audit Log Management Guide.
Hardening baseline
The baseline follows the Apache Tomcat security how-to; every line can be checked automatically.
- Run as a dedicated user: never as root or SYSTEM. Files owned by
root:tomcat, owner read and write, group read only, no world access;logs,tempandworkowned by the Tomcat user; process umask 007 or 0027. Securejava.io.tmpdir(defaults to$CATALINA_BASE/temp). - Remove default web applications: ROOT, docs, examples, and Manager and Host Manager unless required.
- Disable or protect the shutdown port:
<Server port="-1">. - Enable the SecurityListener:
org.apache.catalina.security.SecurityListenerrefuses to start Tomcat as root and checks the umask. Embedded Tomcat (including Spring Boot) does not configure server.xml listeners, so enable it in code. - Trim connectors: TLS only on HTTP connectors that face users, explicit
address, AJP removed or loopback with a secret. - Keep the DefaultServlet safe:
readonlytrue (default) andlistingsfalse (default) inconf/web.xml; setshowServerInfofalse. - Hide error details: on the Host,
<Valve className="org.apache.catalina.valves.ErrorReportValve" showReport="false" showServerInfo="false"/>, or custom error pages per application. - Lock down contexts: leave
crossContext,privilegedandallowLinkingat false. Enabling allowLinking on case-insensitive file systems such as Windows allows direct access toWEB-INF. - Protect realms: LockOutRealm around every realm, CredentialHandler hashing, LDAP over StartTLS or LDAPS.
- Add request filters:
FailedRequestFilterto reject requests with parameter parsing errors andHttpHeaderSecurityFilterfor HSTS and related headers (coordinate with the proxy). - Leave the CGI servlet disabled (the default).
- Isolate untrusted code: the Security Manager can sandbox applications but usually breaks them; for multi-tenant hosting the project recommends a separate Tomcat instance per application, ideally on separate hosts.
Rolling it out
- Inventory: find every Tomcat, including those embedded in vendor products and Spring Boot jars, with branch, version and exposure. See the Attack Surface Management Guide.
- Close internet exposure first: Manager, Host Manager, AJP and JMX reachable from outside the management network are the urgent items.
- Apply the baseline in a test ring: run functional and load tests; watch for applications that relied on PUT, directory listings or cross-context dispatch.
- Promote through pilot and production rings, keeping the previous
conf/directory versioned so rollback is a file swap and a restart. - Enforce continuously: bake the baseline into images or configuration management and alert on drift.
Decision guidance
- Standalone versus embedded: embedded Tomcat in an immutable container image has no Manager and no deployment surface, and patching means rebuilding the image; standalone Tomcat suits shared application servers but carries the Manager, realm files and hot deployment. Prefer embedded or one-application-per-instance where you can, and remember that vendor products often bundle old Tomcat versions that never appear in the patch process.
- AJP versus HTTP proxying: AJP is only worth keeping where an existing httpd or IIS tier depends on it. New designs should proxy HTTP or HTTPS and remove the AJP connector.
- Small versus large estates: a small team can delete the Manager and patch by package; a large estate needs a central inventory of branches, an automated configuration check and a release-tracking process for the Tomcat security pages.
Common misconfigurations
- Write-enabled DefaultServlet: setting
readonly="false"to support an upload feature without authentication allows JSP files to be uploaded and run. Uploads belong in application code with validation, not in the DefaultServlet. - File-based session persistence with a deserialisation gadget on the classpath: a risky combination. Prefer non-persistent or database-backed sessions and remove unused libraries; see the Insecure Deserialisation Guide.
- AJP exposed to the network: older configurations that bound AJP to all addresses without a secret should be rebound to loopback with a secret set. Configuration files copied forward from old versions keep the old attributes.
- Manager with shared or guessable credentials: a single tomcat-users.xml user holding manager-gui and manager-script, reachable from the internet, is a full remote code execution path by design.
- Trusting proxy headers from anywhere: a RemoteIpValve with broad
internalProxies, or a proxy that does not stripX-Forwarded-For, lets attackers spoof a loopback address past IP restrictions.
Framework mapping
| Tomcat control | NIST SP 800-53 Rev. 5 | NIST CSF 2.0 | CIS Controls v8.1 | ISO/IEC 27001:2022 Annex A |
|---|---|---|---|---|
| Remove default apps, unused connectors, CGI | CM-7 Least Functionality | PR.PS-01 | 4.8 Uninstall or disable unnecessary services | A.8.9 Configuration management |
| Hardened server.xml and web.xml baseline | CM-6 Configuration Settings | PR.PS-01 | 4.1 Secure configuration process | A.8.9 |
| Manager roles, RemoteCIDRValve, non-root user | AC-6 Least Privilege | PR.AA-05 | 5.4 Restrict administrator privileges | A.8.2 Privileged access rights |
| CredentialHandler, LockOutRealm, secrets out of conf/ | IA-5 Authenticator Management | PR.AA-01 | 5.2 Use unique passwords | A.5.17 Authentication information |
| TLS connectors, AJP on loopback | SC-8, SC-7 | PR.DS-02 | 3.10 Encrypt sensitive data in transit | A.8.20 Network security |
| AccessLogValve, JSON logs to SIEM | AU-2, AU-12, SI-4 | PR.PS-04, DE.CM-09 | 8.2 Collect audit logs | A.8.15 Logging |
| Track Tomcat security pages, prompt patching, supported branches | SI-2, RA-5, SA-22 | ID.RA-01, PR.PS-02 | 7.4 Automated application patch management | A.8.8 Management of technical vulnerabilities |
Relevant ATT&CK techniques are T1190 Exploit Public-Facing Application, T1505.003 Web Shell, T1110 Brute Force, T1078 Valid Accounts and T1552.001 Credentials In Files. Patching discipline is covered in the Patch Management Guide.
Practitioner checklist
- Inventory every Tomcat instance, including embedded and vendor-bundled copies, with branch and point release.
- Remove ROOT, docs, examples, Host Manager and, where possible, Manager from production.
- If Manager stays: RemoteCIDRValve to the management network, separate manager-gui and manager-script users, hashed passwords, LockOutRealm.
- Remove unused connectors; AJP on loopback with secretRequired="true" or removed; JMX internal only.
- Confirm DefaultServlet readonly is true and listings false; disable the shutdown port.
- Set ErrorReportValve showReport and showServerInfo to false; keep xpoweredBy and allowTrace off.
- Run Tomcat as a non-root user with root:tomcat ownership of conf/ and enable the SecurityListener.
- Move DataSource, keystore and LDAP bind passwords into a secrets manager and record owners and rotation dates.
- Ship access and catalina logs to the SIEM and alert on Manager access, PUT requests and shell processes spawned by the JVM.
- Subscribe to the Tomcat security page for your branch and apply Tomcat security updates promptly (Apache Tomcat 10.x security page).
Standards and references
- Apache Software Foundation: Apache Tomcat 10.1 Security Considerations
- Apache Software Foundation: Apache Tomcat 10.1 Manager App How-To
- Apache Software Foundation: Apache Tomcat 10.1 Realm Configuration How-To
- Apache Software Foundation: Apache Tomcat 10.1 AJP Connector Reference
- Apache Software Foundation: Apache Tomcat 10.x Vulnerabilities
- NIST: SP 800-53 Rev. 5
- MITRE ATT&CK: Web Shell
Related NHI Mgmt Group resources: Java and Spring Security Guide · Oracle WebLogic Server Hardening Guide · Web Application Firewall Guide · Secrets Management Guide