Please star, fork or watch pac4j/pac4j!
Java
Pull request Compare This branch is 1494 commits behind pac4j:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
pac4j-cas
pac4j-core
pac4j-gae
pac4j-http
pac4j-oauth
pac4j-openid
pac4j-saml
pac4j-test-cas
travis
.gitignore
.travis.yml
LICENSE
README-ADFS.txt
README.md
pom.xml

README.md

What is pac4j ? Build Status

pac4j is a Profile & Authentication Client for Java (it's a global rebuilding of the scribe-up library). It targets all the authentication mechanisms supporting the following flow:

  1. From the client application, redirect the user to the "provider" for authentication (HTTP 302)
  2. After successful authentication, redirect back the user from the "provider" to the client application (HTTP 302) and get the user credentials
  3. With these credentials, get the profile of the authenticated user (direct call from the client application to the "provider").

It has a very simple and unified API to support these 6 authentication mechanisms on client side:

  1. OAuth (1.0 & 2.0)
  2. CAS (1.0, 2.0, SAML, logout & proxy)
  3. HTTP (form & basic auth authentications)
  4. OpenID
  5. SAML (2.0)
  6. Google App Engine UserService.

There are 7 libraries implementing pac4j for the following environments:

  1. the CAS server (using the cas-server-support-pac4j library)
  2. the Play 2.x framework (using the play-pac4j_java and play-pac4j_scala libraries)
  3. any basic J2E environment (using the j2e-pac4j library)
  4. the Apache Shiro library (using the buji-pac4j library)
  5. the Spring Security library (using the spring-security-pac4j library)
  6. the Ratpack JVM toolkit (using the ratpack-pac4j module)
  7. the Vertx framework (using the vertx-pac4j module).

It's available under the Apache 2 license.

The "big picture"

Sequence diagram (example: CAS)

Technical description

This Maven project is composed of 6 modules:

pac4j-core

This is the core module of the project with the core classes/interfaces:

  • the Client interface is the main API of the project as it defines the mechanism that all clients must follow: redirect(WebContext,boolean), getCredentials(WebContext) and getUserProfile(Credentials,WebContext)
  • the Credentials class is the base class for all credentials
  • the UserProfile class is the base class for all user profiles (it is associated with attributes definition and converters)
  • the CommonProfile class inherits from the UserProfile class and implements all the common getters that profiles must have (getFirstName(), getEmail()...)
  • the WebContext interface represents a web context which can be implemented in a J2E or another environment.

pac4j-oauth

This module is dedicated to OAuth client support, it's the successor of the scribe-up library:

  • the FacebookClient, TwitterClient... classes are the clients for all the providers: Facebook, Twitter...
  • the OAuthCredentials class is the credentials for OAuth support
  • the FacebookProfile, TwitterProfile... classes are the associated profiles, returned by the clients.

This module is based on the pac4j-core module, the scribe-java library for OAuth protocol support, the Jackson library for JSON parsing and the commons-lang3 library.

pac4j-cas

This module is dedicated to CAS client support:

  • the CasClient class is the client for CAS server (the CasProxyReceptor is dedicated to CAS proxy support)
  • the CasCredentials class is the credentials for CAS support
  • the CasProfile class is the user profile returned by the CasClient.

This module is based on the pac4j-core module and the Jasig CAS client.

pac4j-http

This module is dedicated to HTTP protocol support:

  • the FormClient & BasicAuthClient classes are the client for form and basic auth authentications
  • the UsernamePasswordCredentials class is the username/password credentials in HTTP support
  • the HttpProfile class is the user profile returned by the FormClient and BasicAuthClient.

This module is based on the pac4j-core module and the commons-codec library.

pac4j-openid

This module is dedicated to OpenID protocol support:

  • the YahooOpenIdClient is the client for Yahoo
  • the OpenIdCredentials class is the credentials for OpenID support
  • the YahooOpenIdProfile class is the associated profile, returned by the client.

This module is based on the pac4j-core module and the openid4java library.

pac4j-saml

This module is dedicated to SAML support:

  • the Saml2Client class is the client for integrating with a SAML2 compliant Identity Provider
  • the Saml2Credentials class is the credentials for SAML2 support
  • the Saml2Profile class is the user profile returned by the Saml2Client.

This module is based on the pac4j-core module and the OpenSAML library.

In case you use the library against Microsoft ADFS (Active Directory Federation Services), a SAML Identity Provider server, please have a look into file README-ADFS.txt for details on how to setup your client.

pac4j-test-cas

This module is made to test CAS support in pac4j.

Learn more by browsing the Javadoc.

pac4j-gae

This module is dedicated to Gae connexion login mechanism support:

  • the GaeUserServiceClient is the client for Gae
  • the GaeUserServiceCredentials class is the credentials for gae support
  • the GaeUserServiceProfile class is the associated profile, returned by the client.

This module is based on the pac4j-core module and the Google App Engine API library.

Providers supported

ProviderProtocolMaven dependencyClient classProfile class
CAS serverCASpac4j-casCasClient & CasProxyReceptorCasProfile
CAS server using OAuth WrapperOAuth 2.0pac4j-oauthCasOAuthWrapperClientCasOAuthWrapperProfile
DropBoxOAuth 1.0pac4j-oauthDropBoxClientDropBoxProfile
FacebookOAuth 2.0pac4j-oauthFacebookClientFacebookProfile
GitHubOAuth 2.0pac4j-oauthGitHubClientGitHubProfile
GoogleOAuth 2.0pac4j-oauthGoogle2ClientGoogle2Profile
LinkedInOAuth 1.0 & 2.0pac4j-oauthLinkedInClient & LinkedIn2ClientLinkedInProfile & LinkedIn2Profile
TwitterOAuth 1.0pac4j-oauthTwitterClientTwitterProfile
Windows LiveOAuth 2.0pac4j-oauthWindowsLiveClientWindowsLiveProfile
WordPressOAuth 2.0pac4j-oauthWordPressClientWordPressProfile
YahooOAuth 1.0pac4j-oauthYahooClientYahooProfile
PayPalOAuth 2.0pac4j-oauthPayPalClientPayPalProfile
VkOAuth 2.0pac4j-oauthVkClientVkProfile
FoursquareOAuth 2.0pac4j-oauthFoursquareClientFoursquareProfile
BitbucketOAuth 1.0pac4j-oauthBitbucketClientBitbucketProfile
ORCiDOAuth 2.0pac4j-oauthOrcidClientOrcidProfile
Web sites with basic auth authenticationHTTPpac4j-httpBasicAuthClientHttpProfile
Web sites with form authenticationHTTPpac4j-httpFormClientHttpProfile
YahooOpenIDpac4j-openidYahooOpenIdClientYahooOpenIdProfile
SAML Identity ProviderSAML 2.0pac4j-samlSaml2ClientSaml2Profile
Google App Engine User ServiceGae User Service Mechanismpac4j-gaeGaeUserServiceClientGaeUserServiceProfile

Code sample

Maven dependencies

First, you have define the right dependency: pac4j-oauth for OAuth support or/and pac4j-cas for CAS support or/and pac4j-http for HTTP support or/and pac4j-openid for OpenID support or/and pac4j-saml for SAML support or/and pac4j-gae for Google App Engine support. For example:

<dependency>
  <groupId>org.pac4j</groupId>
  <artifactId>pac4j-oauth</artifactId>
  <version>1.6.0</version>
</dependency>

As the pac4j snapshots libraries are stored in the Sonatype snapshots repository, this repository may need be added in the Maven pom.xml file:

<repository>
  <id>sonatype-nexus-snapshots</id>
  <name>Sonatype Nexus Snapshots</name>
  <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  <releases>
    <enabled>false</enabled>
  </releases>
  <snapshots>
    <enabled>true</enabled>
  </snapshots>
</repository>

OAuth support

If you want to authenticate and get the user profile from Facebook, you have to use the org.pac4j.oauth.client.FacebookClient:

// declare the client (use default scope and fields)
FacebookClient client = new FacebookClient(MY_KEY, MY_SECRET);
// define the client application callback url
client.setCallbackUrl("http://myserver/myapp/callbackUrl");
// send the user to Facebook for authentication and permissions
WebContext context = new J2EContext(request, response);
client.redirect(context, false);

...after successful authentication, in the client application, on the callback url (for Facebook)...

// get OAuth credentials
OAuthCredentials credentials = client.getCredentials(context);
// get the facebook profile
FacebookProfile facebookProfile = client.getUserProfile(credentials, context);
System.out.println("Hello: " + facebookProfile.getDisplayName() + " born the " + facebookProfile.getBirthday());</code></pre>

CAS support

For integrating an application with a CAS server, you should use the org.pac4j.cas.client.CasClient:

// declare the client
CasClient client = new CasClient();
// define the client application callback url
client.setCallbackUrl("http://myserver/myapp/callbackUrl");
// send the user to the CAS server for authentication
WebContext context = new J2EContext(request, response);
client.redirect(context, false);

...after successful authentication, in the client application, on the callback url...

// get CAS credentials
CasCredentials credentials = client.getCredentials(context);
// get the CAS profile
CasProfile casProfile = client.getUserProfile(credentials, context);
System.out.println("Hello: " + casProfile.getAttribute("anAttribute"));</code></pre>

For proxy support, the org.pac4j.cas.client.CasProxyReceptor class must be used (on the same or new callback url) and declared within the CasClient class:

casClient.setCasProxyReceptor(new CasProxyReceptor());
// casClient.setAcceptAnyProxy(false);
// casClient.setAllowedProxyChains(proxies);

In this case, the org.pac4j.cas.profile.CasProxyProfile must be used to get proxy tickets for other CAS services:

CasProxyProfile casProxyProfile = (CasProxyProfile) casProfile;
String proxyTicket = casProxyProfile.getProxyTicketFor(anotherCasService);

HTTP support

To use form authentication in a web application, you should use the org.pac4j.http.client.FormClient class:

// declare the client
FormClient client = new FormClient("/myloginurl", new MyUsernamePasswordAuthenticator());
client.setCallbackUrl("http://myserver/myapp/callbackUrl");
// send the user to the form for authentication
WebContext context = new J2EContext(request, response);
client.redirect(context, false);

...after successful authentication...

// get username/password credentials
UsernamePasswordCredentials credentials = client.getCredentials(context);
// get the HTTP profile
HttpProfile httpProfile = client.getUserProfile(credentials, context);
System.out.println("Hello: " + httpProfile.getUsername());</code></pre>

To use basic auth authentication in a web application, you should use the org.pac4j.http.client.BasicAuthClient class the same way:

// declare the client
BasicAuthClient client = new BasicAuthClient(new MyUsernamePasswordAuthenticator(), new UsernameProfileCreator());

OpenID support

To use Yahoo and OpenID for authentication, you should use the org.pac4j.openid.client.YahooOpenIdClient class:

// declare the client
YahooOpenIdClient client = new YahooOpenIdClient();
client.setCallbackUrl("/callbackUrl");
// send the user to Yahoo for authentication
WebContext context = new J2EContext(request, response);
// we assume the user identifier is in the "openIdUser" request parameter
client.redirect(context, false);

...after successful authentication, in the client application, on the callback url...

// get the OpenID credentials
OpenIdCredentials credentials = client.getCredentials(context);
// get the YahooOpenID profile
YahooOpenIdProfile profile = client.getUserProfile(credentials, context);
System.out.println("Hello: " + profile.getDisplayName());

SAML support

For integrating an application with a SAML2 Identity Provider server, you should use the org.pac4j.saml.client.Saml2Client:

//Generate a keystore for all signature and encryption stuff:
keytool -genkeypair -alias pac4j-demo -keypass pac4j-demo-passwd -keystore samlKeystore.jks -storepass pac4j-demo-passwd -keyalg RSA -keysize 2048 -validity 3650

// declare the client
Saml2Client client = new Saml2Client();
// configure keystore
client.setKeystorePath("samlKeystore.jks");
client.setKeystorePassword("pac4j-demo-passwd");
client.setPrivateKeyPassword("pac4j-demo-passwd");
// Configure a file containing the Identity Provider (IDP) metadata.
// It is the IDP's responsibility to make its metadata freely accessible.
client.setIdpMetadataPath("testshib-providers.xml");
// Configure the callback url either directly or with the Clients container
// The callback url will be the SP entity ID
client.setCallbackUrl("http://localhost:8080/callback");

// generate pac4j SAML2 Service Provider metadata to import on Identity Provider side
String spMetadata = client.printClientMetadata();

// send the user to the Identity Provider server for authentication
WebContext context = new J2EContext(request, response);
client.redirect(context, false);

...after successful authentication, in the Service Provider application, on the assertion consumer service url...

// get SAML2 credentials
Saml2Credentials credentials = client.getCredentials(context);
// get the SAML2 profile
Saml2Profile saml2Profile = client.getUserProfile(credentials, context);

Additional configuration:

Once you have an authenticated web session on the Identity Provider, usually it won't prompt you again to enter your credentials and it will automatically generate you a new assertion. By default, the SAML pac4j client will accept assertions based on a previous authentication for one hour. If you want to change this behaviour, set the maximumAuthenticationLifetime parameter:

// Lifetime in seconds
client.setMaximumAuthenticationLifetime(600);

By default, the entity ID of your application (the Service Provider) will be equals to the pac4j callback url. This can lead to problems with some IDP because of the query string not being accepted (like ADFS2.0). You can force your own entity ID with the spEntityId parameter:

// custom SP entity ID
client.setSpEntityId("http://localhost:8080/callback");

Gae User Service support

To use the Google App Engine authentication, you should use the org.pac4j.gae.client.GaeUserServiceClient class:

// declare the client
GaeUserServiceClient client = new GaeUserServiceClient();
client.setCallbackUrl("/callbackUrl");
// send the user to Google for authentication
WebContext context = new J2EContext(request, response);
client.redirect(context, false);

...after successful authentication, in the client application, on the callback url...

// get the OpenID credentials
GaeUserServiceCredentials credentials = client.getCredentials(context);
// get the GooglOpenID profile
GaeUserServiceProfile profile = client.getUserProfile(credentials, context);
System.out.println("Hello: " + profile.getDisplayName());

Multiple clients

If you use multiple clients, you can use more generic objects. All profiles inherit from the org.pac4j.core.profile.CommonProfile class:

// get credentials
Credentials credentials = client.getCredentials(context);
// get the common profile
CommonProfile commonProfile = client.getUserProfile(credentials, context);
System.out.println("Hello: " + commonProfile.getFirstName());

If you want to interact more with the OAuth providers (like Facebook), you can retrieve the access token from the (OAuth) profiles:

OAuthProfile oauthProfile = (OAuthProfile) commonProfile;
String accessToken = oauthProfile.getAccessToken();
// or
String accesstoken = facebookProfile.getAccessToken();

You can also group all clients on a single callback url by using the org.pac4j.core.client.Clients class:

Clients clients = new Clients("http://server/app/callbackUrl", fbClient, casClient, formClient yahooOpenIdClient, samlClient);
// on the callback url, retrieve the right client
Client client = clients.findClient(context);

Error handling

All methods of the clients may throw an unchecked org.pac4j.core.exception.TechnicalException, which could be trapped by an appropriate try/catch. The getRedirectionUrl(WebContext,boolean,boolean) and the getCredentials(WebContext) methods may also throw a checked org.pac4j.core.exception.RequiresHttpAction, to require some additionnal HTTP action (redirection, basic auth...)

Authorizations

Although the primary target of the pac4j library is to deal with authentication, authorizations can be handled as well.

After a successful authentication at a provider, the associated client can generate roles, permissions and a "remembered" status. These information are available in every user profile.

The generation of this information is controlled by a class implementing the org.pac4j.core.authorization.AuthorizationGenerator interface and set for this client.

FromAttributesAuthorizationGenerator authGenerator = new FromAttributesAuthorizationGenerator(new String[]{"attribRole1"}, new String[]{"attribPermission1"})
client.setAuthorizationGenerator(authGenerator);

Libraries built with pac4j

Even if you can use pac4j on its own, this library is used to be integrated with:

  1. the cas-server-support-pac4j module to add multi-protocols client support to the CAS server
  2. the play-pac4j library to add multi-protocols client support to the Play 2.x framework in Java and Scala
  3. the j2e-pac4j library to add multi-protocols client support to the J2E environment
  4. the buji-pac4j library to add multi-protocols client support to the Apache Shiro project
  5. the spring-security-pac4j library to add multi-protocols client support to Spring Security
  6. the ratpack-pac4j module to add multi-protocols client support to Ratpack
  7. the vertx-pac4j module to add multi-protocols client support to Vertx
Integration libraryProtocol(s) supportedBased onDemo webapp
cas-server-support-pac4j 4.0.0OAuth / CAS / OpenIDpac4j 1.4.1cas-pac4-oauth-demo
play-pac4j 1.3.0 / 1.2.2 / 1.1.4OAuth / CAS / OpenID / HTTP / SAML / GAEpac4j 1.6.0play-pac4j-java-demo
play-pac4j-scala-demo
j2e-pac4j 1.0.4OAuth / CAS / OpenID / HTTP / SAML / GAEpac4j 1.6.0j2e-pac4j-demo
buji-pac4j 1.3.0OAuth / CAS / OpenID / HTTP / SAML / GAEpac4j 1.6.0buji-pac4j-demo
spring-security-pac4j 1.2.4OAuth / CAS / OpenID / HTTP / SAML / GAEpac4j 1.6.0spring-security-pac4j-demo
ratpack 0.9.7OAuth / CAS / OpenID / HTTPpac4j 1.5.1ratpack-pac4j-demo
vertx-pac4j 1.0.0OAuth / CAS / OpenID / HTTP / SAML / GAEpac4j 1.6.0vertx-pac4j-demo

Versions

The current version 1.6.1-SNAPSHOT is under development.
The build is done on Travis: https://travis-ci.org/leleuj/pac4j. The generated artifacts are available on the Sonatype snapshots repository as a Maven dependency.

The last released version is the 1.6.0:

<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-core</artifactId>
    <version>1.6.0</version>
</dependency>

See the release notes.

Testing

pac4j is tested by more than 400:

  • unit and bench tests launched by mvn test
  • integration tests (authentication processes are fully simulated using the HtmlUnit library) launched by mvn verify.

Bugs / Features tracking

Bugs and new features can now be tracked using JIRA.

Contact

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