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.
They depend on the pac4j-core
module (groupId: org.pac4j
):
- the SSO CAS server using the cas-server-support-pac4j module (demo: cas-pac4j-oauth-demo)
- the Play 2.x framework using the the play-pac4j library (demos: play-pac4j-java-demo & play-pac4j-scala-demo)
- any J2E environment using the j2e-pac4j library (demo: j2e-pac4j-demo)
- the Apache Shiro project library using the buji-pac4j library (demo: buji-pac4j-demo)
- the Spring Security library using the spring-security-pac4j library (demo: spring-security-pac4j-demo)
- the Ratpack JVM toolkit using the ratpack-pac4j module (demo: ratpack-pac4j-demo)
- the Vertx framework using the vertx-pac4j module (demo: vertx-pac4j-demo)
- the Undertow web server using the undertow-pac4j module (demo: undertow-pac4j-demo)
- the Spark Java framework using the spark-pac4j library (demo: spark-pac4j-demo)
- the Jooby framework using the jooby-pac4j module (demo: jooby-pac4j-demo)
pac4j
supports the main authentication mechanisms (via stateful / indirect clients for UI based on external identity providers and stateless / direct clients for web services using internal credentials authenticators and user profile creators):
- OAuth (1.0 & 2.0): Facebook, Twitter, Google, Yahoo, LinkedIn, Github... using the
pac4j-oauth
module - CAS (1.0, 2.0, 3.0, SAML, logout, proxy, REST) using the
pac4j-cas
module - HTTP (form, basic auth, IP, header, cookie, GET/POST parameter) using the
pac4j-http
module - OpenID using the
pac4j-openid
module - SAML (2.0) using the
pac4j-saml
module - Google App Engine UserService using the
pac4j-gae
module - OpenID Connect (1.0) using the
pac4j-oidc
module - JWT using the
pac4j-jwt
module - LDAP using the
pac4j-ldap
module - Relational DB using the
pac4j-sql
module - MongoDB using the
pac4j-mongo
module - Stormpath using the
pac4j-stormpath
module.
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
".
The current version 1.8.0-RC2-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 built locally via Maven:
git clone [email protected]: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.
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());
- 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.
- 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.
If you have any question, please use the following mailing lists: