tempbottle / pac4j

Security engine for Java (authentication, authorization, multi frameworks)

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 currently available for many frameworks / tools and supports many authentication mechanisms. See the big picture.

Its core API is provided by the pac4j-core submodule (groupId: org.pac4j).

Frameworks / tools implementing pac4j:

The framework / tool you develop with	The *-pac4j library you must use	The demo(s) for tests
J2E environment	j2e-pac4j	j2e-pac4j-demo
Spring Web MVC and Spring Boot	spring-webmvc-pac4j	spring-webmvc-pac4j-demo or spring-webmvc-pac4j-boot-demo
Play 2.x framework	play-pac4j	play-pac4j-java-demo or play-pac4j-scala-demo
Vertx	vertx-pac4j	vertx-pac4j-demo
Spark Java framework	spark-pac4j	spark-pac4j-demo
Ratpack	ratpack-pac4j	ratpack-pac4j-demo
Undertow	undertow-pac4j	undertow-pac4j-demo
Jooby framework	jooby-pac4j	jooby-pac4j-demo
Apache Shiro	buji-pac4j	buji-pac4j-demo
Spring Security	spring-security-pac4j	spring-security-pac4j-demo
SSO CAS server	cas-server-support-pac4j	cas-pac4j-oauth-demo

Supported authentication / authorization mechanisms:

pac4j supports most authentication mechanisms, called clients:

• indirect / stateful clients are for UI when the user authenticates once at an external provider (like Facebook, a CAS server...) or via a local form (or basic auth popup)
• direct / stateless clients are for web services when credentials (like basic auth, tokens...) are passed for each HTTP request.

See the authentication flows.

The authentication mechanism you want	The pac4j-* submodule(s) you must use
OAuth (1.0 & 2.0): Facebook, Twitter, Google, Yahoo, LinkedIn, Github...	pac4j-oauth
CAS (1.0, 2.0, 3.0, SAML, logout, proxy)	pac4j-cas
SAML (2.0)	pac4j-saml
OpenID Connect (1.0)	pac4j-oidc
HTTP (form, basic auth, IP, header, cookie, GET/POST parameter) + JWT or LDAP or Relational DB or MongoDB or Stormpath or CAS REST API	pac4j-http + pac4j-jwt or pac4j-ldap or pac4j-sql or pac4j-mongo or pac4j-stormpath or pac4j-cas
Google App Engine UserService	pac4j-gae
OpenID	pac4j-openid

pac4j supports many authorization checks, called authorizers available in the pac4j-core (and pac4j-http) submodules: role / permission checks, IP check, profile type verification, HTTP method verification... as well as regular security protections for CSRF, XSS, cache control, Xframe...

How to develop you own pac4j implementation for your framework / tool?

Versions

The next version 1.8.1-SNAPSHOT is under development. Maven artifacts are built via Travis: and available in the Sonatype snapshots repository. See the tests strategy.

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

git clone [email protected]:pac4j/pac4j.git
cd pac4j
mvn clean install

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. 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 define your security configuration, 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());

Notice you may also use the ConfigSingleton object to keep one instance of your configuration and share it among the different components (if you don't have any dependency injection capability). You can also use the ConfigFactory to build you configuration if no other mean is available.

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

1. For your protection "filter", it must be based on two String parameters: clientName (list of clients used for authentication) and authorizerName (list of authorizers to check authorizations) and 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