javalin-pac4j is the Javalin implementation of pac4j, the security engine for Java. If it is useful to you, please ⭐ star pac4j on GitHub: it helps other developers discover it!

The javalin-pac4j project is an easy and powerful security library for Javalin web applications which supports authentication and authorization, but also logout and advanced features like protection against session fixation and CSRF.

It's based on Java 17 and the pac4j security engine v6. It's available under the Apache 2 license.

Main concepts and components:

1. A client represents an authentication mechanism. It performs the login process and returns a user profile. An indirect client is for UI authentication while a direct client is for web services authentication:

▸ OpenID Connect - SAML - CAS - OAuth - HTTP - LDAP - SQL - JWT - MongoDB - IP address

2. An authorizer is meant to check authorizations on the authenticated user profile(s) or on the current web context:

▸ Roles / permissions - Anonymous / remember-me / (fully) authenticated - Profile type, attribute - CORS - CSRF - Security headers - IP address, HTTP method

3. A matcher defines whether the SecurityHandler must be applied and can be used for additional web processing

4. The SecurityHandler protects a URL by checking that the user is authenticated and that the authorizations are valid, according to the clients and authorizers configuration. If the user is not authenticated, it performs authentication for direct clients or starts the login process for indirect clients

5. The CallbackHandler finishes the login process for an indirect client

6. The LogoutHandler handles the logout process.

Just follow these easy steps to secure your Javalin application:

1) Add the required dependencies (javalin-pac4j and pac4j-* libraries)

The table below summarizes the dependency versions used by the released artifacts:

javalin-pac4j	JDK	pac4j	Javalin
v8	17	v6	v7
v7	17	v6	v5.6
v6	11	v5	v5.1
v5	11	v5	v3.13
v3	8	v4	v3.8

For the latest released version, you need to add a dependency for:

• the javalin-pac4j library (groupId: org.pac4j, version: 8.0.1)
• the appropriate pac4j submodules (groupId: org.pac4j, version: 6.5.9): pac4j-oauth for OAuth support (Facebook, Twitter...), pac4j-cas for CAS support, pac4j-ldap for LDAP authentication, etc.

Version 8.0.1 uses Java 17 and Javalin 7.2.3.

All released artifacts are available on Maven Central: .

2) Define the configuration

The configuration (org.pac4j.core.config.Config) contains all the clients and authorizers required by the application to handle security.

• ConfigFactory example
• Authorizer example
• Authenticator example

3) Protect URLs

Create a SecurityHandler instance and register it as a before handler that covers the URLs you want to protect. The example app shows an implementation for every client.

4) Define the callback endpoint only for indirect clients (CallbackHandler)

For indirect clients (like Facebook), the user is redirected to an external identity provider for login and then back to the application. The example app shows an implementation.

Since version 8.0.1: when the callback request does not identify a client and no explicit fallback is configured, pac4j selects the only indirect client, if there is exactly one. To configure a fallback explicitly when using multiple indirect clients, use new CallbackHandler(config, "/", true, "FormClient") or set the handler's defaultClient field. The first client in the configuration is no longer implicitly used as the fallback. These changes are not available in 8.0.0.

5) Get the user profile (via HttpServletRequest or ProfileManager)

The example app shows an implementation.

6) Logout (LogoutHandler)

You can have a local logout or a global logout. The example app shows both implementations.

Need help?

You can use the mailing lists or the commercial support.

Development

Snapshot artifacts are built via GitHub Actions and published to the Central Portal Snapshots repository. The current development version is 8.0.2-SNAPSHOT, using pac4j 6.5.9 and Javalin 7.2.3. To use snapshot artifacts, add this repository to your Maven pom.xml:

<repositories>
  <repository>
    <name>Central Portal Snapshots</name>
    <id>central-portal-snapshots</id>
    <url>https://central.sonatype.com/repository/maven-snapshots/</url>
    <releases>
      <enabled>false</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>