为何Keycloak文档不建议WAR部署时使用Spring Boot适配器？

Great question! It’s totally reasonable to be confused when both setups work perfectly today—let’s break down why the documentation recommends sticking with the Tomcat adapter for WAR deployments, even if things seem smooth right now:

• Avoiding Configuration Conflicts
  The Spring Boot adapter is built for embedded server scenarios, where it controls the entire security stack from within your app. When you deploy as a WAR to Tomcat, you’re mixing Spring Boot’s application-level security with Tomcat’s native container security. While this might not cause issues immediately, over time you could run into subtle conflicts: duplicate authentication filters, mismatched session management rules, or conflicting security headers that only surface under high load or edge cases. The Tomcat adapter integrates directly with Tomcat’s security layer, eliminating these potential clashes.

• Leveraging Tomcat’s Native Features
  The Spring Boot adapter doesn’t play nicely with all of Tomcat’s built-in security capabilities. For example, if you ever need to set up single sign-on across multiple WARs on the same Tomcat instance, use Tomcat’s realm integration, or rely on container-managed SSL termination, the Spring Boot adapter will force you to work around its limitations. The Tomcat adapter is purpose-built to use these native features seamlessly.

• Long-Term Compatibility & Maintenance
  Keycloak’s team tests the Tomcat adapter extensively with Tomcat’s lifecycle and security model. Using the Spring Boot adapter for WAR deployments puts you in an "unsupported edge case." Future updates to Keycloak, Spring Boot, or Tomcat could introduce breaking changes that only affect this setup—and those changes might not be prioritized for fixes since it’s not the intended use case.

• Simpler, More Maintainable Configuration
  Managing two separate security configuration models (Spring Boot’s auto-config + Tomcat’s settings) makes your setup harder to debug and maintain down the line. If you hit an issue later, you’ll have to trace through both layers instead of a single, unified Tomcat adapter setup. The XML configuration recommended for Tomcat keeps all security logic aligned with how Tomcat expects to handle authentication, making it easier for other developers familiar with Tomcat to understand and modify.

It’s totally normal that both approaches work today—Keycloak’s adapters are robust! But the documentation’s warning is focused on long-term stability, avoiding hidden issues, and using the right tool for the container environment.

内容的提问来源于stack exchange，提问作者dgr018