pac4j: A Java Security Engine That Trades Simplicity for Coverage

What pac4j Actually Solves

pac4j positions itself as a security engine for Java, not a single-purpose client. The core problem it addresses is fragmentation: a Java application might need to authenticate via OpenID Connect, SAML2, CAS, OAuth, LDAP, or JWT, and it might run on Spring MVC, Play, Vert.x, or any of a dozen other stacks. Without a common abstraction, each protocol and framework combination would require its own integration code. pac4j provides that abstraction in the form of clients, authenticators, authorizers, and matchers. The intended audience is a team building a web application or web service that must support multiple authentication mechanisms, or that plans to change frameworks without rewriting security logic. The README lists over fifteen framework integrations, from Spring Boot to Akka HTTP, which signals a deliberate strategy of covering the Java ecosystem broadly rather than deeply.

The Four-Part Architecture: Clients, Authenticators, Authorizers, Matchers

The documentation organizes pac4j around four component types, and the README reflects that structure. Clients handle external protocol interactions: OpenID Connect, SAML, CAS, OAuth, HTTP, and Kerberos are listed as clients. Authenticators validate credentials against a backend: LDAP, SQL, JWT, MongoDB, IP address, and REST API. Authorizers decide whether an authenticated profile may proceed, with roles, authentication levels (anonymous, remember-me, fully authenticated), profile type, and attribute checks. Matchers apply conditions to requests, including CORS, security headers, IP address, and HTTP method. This separation means you can mix a SAML client with an LDAP authenticator, or a JWT authenticator with a CORS matcher. The data flow is typical: a request hits a matcher, then a client attempts authentication, producing a profile, then an authorizer evaluates that profile. The design is modular, but it also means you must understand four distinct concepts before you can configure anything nontrivial.

Getting It Running: Version Matrix and Maven Coordinates

The README includes a version table that is critical for adoption. pac4j v6.x requires JDK 17 and uses Lombok. v5.x targets JDK 11 and does not use Lombok. v4.x targets JDK 8 and also avoids Lombok. This is a hard constraint: if your organization is still on Java 8, you are limited to v4.x, which may lack newer protocol features. The README links to the Maven Central repository for the latest version, but it does not give explicit dependency coordinates in the text. In practice, you would add a dependency on org.pac4j:pac4j-core and the specific client modules you need, plus a framework integration artifact like spring-webmvc-pac4j. The README points to each integration's own repository for getting started. The presence of a separate 'next version' page suggests active development, but the lack of a direct 'quick start' snippet in the README means you have to read the documentation site to find a minimal configuration. That is a friction point for a library whose selling point is ease.

Framework Integrations: Breadth or Bait?

The README lists integrations for Spring Web MVC, Spring Webflux, J2E, Apache Shiro, Spring Security, CAS server, Syncope, Apache Knox, Play, Vert.x, Spark Java, Ratpack, JAX-RS, Dropwizard, Javalin, Pippo, Undertow, Lagom, Akka HTTP, and Jooby. That is an impressive list, but it raises a question: are all these integrations maintained at the same level? The README does not say. Some are official pac4j projects, like spring-webmvc-pac4j and play-pac4j. Others are third-party, like the Akka HTTP integration from StackVista and the Shiro integration from bujiio. For a production team, that distinction matters. An official integration is more likely to track pac4j core releases and fix security issues promptly. A third-party integration may lag or be abandoned. The README does not provide maintenance status for each, so you must check each repository separately. That is a real cost, and it undercuts the promise of a single security layer across frameworks.

Authorization and Web Security: Not Just Authentication

pac4j is not only about logging users in. The README lists explicit authorization mechanisms: roles, authentication levels, profile type and attribute checks, plus web-level protections like CORS, CSRF, and security headers. This is a broader scope than many authentication libraries, which stop at profile retrieval. The inclusion of CSRF and security headers as matchers or authorizers means pac4j can handle parts of what a dedicated web security filter does. However, the list is not exhaustive. There is no mention of rate limiting, input validation, or session fixation protection. So pac4j replaces the authentication and basic authorization layer, but you still need a web framework's security features or a separate library for other concerns. The documentation pages for these mechanisms are separate, so you must read each one to understand how to configure, say, a CSRF token check. The README's summary is a menu, not a manual.

Advanced Mechanisms: OpenID Federation and EUDI Wallet

The README lists OpenID Federation and EUDI Wallet/eIDAS 2.0 as advanced mechanisms. OpenID Federation is a relatively new specification for trust establishment between identity providers and relying parties. EUDI Wallet refers to the European Digital Identity Wallet, a regulatory-driven initiative. These are cutting-edge areas, and pac4j's inclusion suggests an ambition to stay ahead of regulatory and protocol developments. But 'advanced' also implies less maturity and fewer real-world deployments. If your project needs OpenID Federation today, you are likely on the bleeding edge, and you should expect API changes and incomplete documentation. The README does not provide details on how these mechanisms work or what the implementation status is. That is a risk for adopters who need production stability. For most teams, these features are irrelevant, but they show that pac4j is not resting on OAuth and SAML alone.

Licensing, Support, and Maintenance Costs

pac4j is licensed under Apache-2.0, which is permissive and allows commercial use, modification, and redistribution without copyleft obligations. That is a low-legal-risk choice for enterprises. The README mentions mailing lists and commercial support from a company called CAS in the Cloud, which also sponsors the project. That dual model is common: free community support plus paid consulting. For maintenance, the version table is the key cost driver. Upgrading pac4j may force a JDK upgrade: moving from v5.x to v6.x requires JDK 17, and v6.x introduces Lombok, which some teams dislike because it adds a compile-time dependency and can obscure code. The README does not state a release cadence or a support window for older versions. You must assume that v4.x on Java 8 receives no updates, which could be a security concern. The 'next version' page implies continuous development, but you should budget time to track releases and test upgrades against your framework integration.

Editorial conclusion

Adopt pac4j if you need one security layer across multiple Java frameworks or protocols, especially in a Spring Boot, Play, or Vert.x environment. Avoid it if you only need a single protocol on a single framework, where a dedicated client library is simpler. Before adopting, verify the current v6.x API against your JDK 17 baseline, confirm the integration module for your exact framework version is maintained, and check the documentation for your protocol, as some clients like OpenID Federation are still advanced and less proven.

Official sources

1. Official documentation
2. Official README
3. Project repository