What is pac4j?

pac4j is a Java security engine to authenticate users, get their profiles and manage their authorizations in order to secure your Java web applications. It's available under the Apache 2 license.

It is actually implemented by many frameworks and supports many authentication mechanisms. See the big picture.

Frameworks / tools implementing pac4j:

They depend on the pac4j-core module (groupId: org.pac4j):

1. the SSO CAS server using the cas-server-support-pac4j module (demo: cas-pac4j-oauth-demo)
2. the Play 2.x framework using the the play-pac4j library (demos: play-pac4j-java-demo & play-pac4j-scala-demo)
3. any J2E environment using the j2e-pac4j library (demo: j2e-pac4j-demo)
4. the Apache Shiro project library using the buji-pac4j library (demo: buji-pac4j-demo)
5. the Spring Security library using the spring-security-pac4j library (demo: spring-security-pac4j-demo)
6. the Ratpack JVM toolkit using the ratpack-pac4j module (demo: ratpack-pac4j-demo)
7. the Vertx framework using the vertx-pac4j module (demo: vertx-pac4j-demo)
8. the Undertow web server using the undertow-pac4j module (demo: undertow-pac4j-demo)
9. the Spark Java framework using the spark-pac4j library (demo: spark-pac4j-demo)
10. the Jooby framework using the jooby-pac4j module (demo: jooby-pac4j-demo)

Supported authentication mechanisms:

pac4j supports stateful / indirect and stateless / direct authentication flows using external identity providers or internal credentials authenticators and user profile creators:

1. OAuth (1.0 & 2.0): Facebook, Twitter, Google, Yahoo, LinkedIn, Github... using the pac4j-oauth module
2. CAS (1.0, 2.0, SAML, logout & proxy) + REST API support using the pac4j-cas module
3. HTTP (form, basic auth, IP, header, GET/POST parameter authentications) using the pac4j-http module
4. OpenID using the pac4j-openid module
5. SAML (2.0) using the pac4j-saml module
6. Google App Engine UserService using the pac4j-gae module
7. OpenID Connect 1.0 using the pac4j-oidc module
8. JWT using the pac4j-jwt module
9. LDAP using the pac4j-ldap module
10. relational DB using the pac4j-sql module
11. MongoDB using the pac4j-mongo module
12. Stormpath using the pac4j-stormpath module.

How to use pac4j for a specific framework?

Read the appropriate documentation for the SSO CAS server, Play 2.x framework, J2E, Apache Shiro, Spring Security, Ratpack, Vertx, Undertow, Spark Java framework or Jooby. See the "Frameworks / tools implementing pac4j".

How to implement pac4j for your own framework?

Versions

The current version 1.8.0-RC2-SNAPSHOT is under development. Maven artefacts are built via Travis: and available in the Sonatype snapshots repository. See the tests strategy.

The source code can be cloned and built locally via Maven:

git clone git@github.com:pac4j/pac4j.git
cd pac4j
mvn clean install -DskipITs

The latest released version is the , available in the Maven central repository. See the release notes.

Implementations

pac4j is an easy and powerful security engine which can be used in many ways.

Add the pac4j-core dependency to benefit from the core API of pac4j. Other dependencies will be optionally added for specific support: pac4j-oauth for OAuth, pac4j-cas for CAS, pac4j-saml for SAML...

To secure your Java web application, a good implementation is to create two filters: one to protect urls, the other one to receive callbacks for stateful authentication processes ("indirect clients").

Gather all your authentication mechanisms = clients via the Clients class (to share the same callback url). Also define your authorizers to check authorizations and aggregate both (clients and authorizers) on the Config:

FacebookClient facebookClient = new FacebookClient(FB_KEY, FB_SECRET);
TwitterClient twitterClient = new TwitterClient(TW_KEY, TW_SECRET);
FormClient formClient = new FormClient("http://localhost:8080/theForm.jsp", new SimpleTestUsernamePasswordAuthenticator(), new UsernameProfileCreator());
CasClient casClient = new CasClient();
casClient.setCasLoginUrl("http://mycasserver/login");
Clients clients = new Clients("http://localhost:8080/callback", facebookClient, twitterClient, formClient, casClient);
Config config = new Config(clients);
config.addAuthorizer("admin", new RequireAnyRoleAuthorizer("ROLE_ADMIN"));
config.addAuthorizer("custom", new CustomAuthorizer());

1. For your protection filter, use the following logic (loop on direct clients for authentication then check the user profile and authorizations):

EnvSpecificWebContext context = new EnvSpecificWebContex(...);
Clients configClients = config.getClients();
List<Client> currentClients = clientFinder.find(configClients, context, clientName);

boolean useSession = useSession(context, currentClients);
ProfileManager manager = new ProfileManager(context);
UserProfile profile = manager.get(useSession);

if (profile == null && currentClients != null && currentClients.size() > 0) {
  for (final Client currentClient: currentClients) {
    if (currentClient instanceof DirectClient) {
      final Credentials credentials;
      try {
        credentials = currentClient.getCredentials(context);
      } catch (RequiresHttpAction e) { ... }
      profile = currentClient.getUserProfile(credentials, context);
      if (profile != null) {
        manager.save(useSession, profile);
        break;
      }
    }
  }
}

if (profile != null) {
  if (authorizationChecker.isAuthorized(context, profile, authorizerName, config.getAuthorizers())) {
    grantAccess();
  } else {
    forbidden(context, currentClients, profile);
  }
} else {
  if (startAuthentication(context, currentClients)) {
    saveRequestedUrl(context, currentClients);
    redirectToIdentityProvider(context, currentClients);
  } else {
    unauthorized(context, currentClients);
  }
}

The EnvSpecificWebContext class is a specific implementation of the WebContext interface for your framework.

See the final implementations in j2e-pac4j and play-pac4j.

2. For your callback filter, get the credentials and the user profile on the callback url:

EnvSpecificWebContext context = new EnvSpecificWebContex(...);
Clients clients = config.getClients();
Client client = clients.findClient(context);

Credentials credentials;
try {
  credentials = client.getCredentials(context);
} catch (RequiresHttpAction e) {
  handleSpecialHttpBehaviours();
}

UserProfile profile = client.getUserProfile(credentials, context);
saveUserProfile(context, profile);
redirectToOriginallyRequestedUrl(context, response);

See the final implementations in j2e-pac4j and play-pac4j.

Read the Javadoc and the technical components for more information.

Need help?

If you have any question, please use the following mailing lists:

• pac4j users
• pac4j developers