README.md

• What is pac4j ?
• The "big picture"
• Sequence diagram (example: CAS)
• Technical description
  • pac4j-core
  • pac4j-oauth
  • pac4j-cas
  • pac4j-http
  • pac4j-openid
  • pac4j-saml
  • pac4j-test-cas
• Providers supported
• Code sample
  • Maven dependencies
  • OAuth support
  • CAS support
  • HTTP support
  • OpenID support
  • SAML support
  • Multiple clients
  • Error handling
  • Authorizations
• Libraries built with pac4j
• Versions
• Testing
• Bugs / Features tracking
• Contact

What is pac4j ?

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

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 5 protocols 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) (still experimental)

There are 6 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).

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,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 GoogleOpenIdClient is the client for Google
• the OpenIdCredentials class is the credentials for OpenID support
• the GoogleOpenIdProfile 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.

pac4j-test-cas

This module is made to test CAS support in pac4j.

Learn more by browsing the Javadoc.

Providers supported

Provider	Protocol	Maven dependency	Client class	Profile class
CAS server	CAS	pac4j-cas	CasClient & CasProxyReceptor	CasProfile
CAS server using OAuth Wrapper	OAuth 2.0	pac4j-oauth	CasOAuthWrapperClient	CasOAuthWrapperProfile
DropBox	OAuth 1.0	pac4j-oauth	DropBoxClient	DropBoxProfile
Facebook	OAuth 2.0	pac4j-oauth	FacebookClient	FacebookProfile
GitHub	OAuth 2.0	pac4j-oauth	GitHubClient	GitHubProfile
Google	OAuth 2.0	pac4j-oauth	Google2Client	Google2Profile
LinkedIn	OAuth 1.0 & 2.0	pac4j-oauth	LinkedInClient & LinkedIn2Client	LinkedInProfile & LinkedIn2Profile
Twitter	OAuth 1.0	pac4j-oauth	TwitterClient	TwitterProfile
Windows Live	OAuth 2.0	pac4j-oauth	WindowsLiveClient	WindowsLiveProfile
WordPress	OAuth 2.0	pac4j-oauth	WordPressClient	WordPressProfile
Yahoo	OAuth 1.0	pac4j-oauth	YahooClient	YahooProfile
PayPal	OAuth 2.0	pac4j-oauth	PayPalClient	PayPalProfile
Vk	OAuth 2.0	pac4j-oauth	VkClient	VkProfile
Foursquare	OAuth 2.0	pac4j-oauth	FoursquareClient	FoursquareProfile
Bitbucket	OAuth 1.0	pac4j-oauth	BitbucketClient	BitbucketProfile
Web sites with basic auth authentication	HTTP	pac4j-http	BasicAuthClient	HttpProfile
Web sites with form authentication	HTTP	pac4j-http	FormClient	HttpProfile
Google	OpenID	pac4j-openid	GoogleOpenIdClient	GoogleOpenIdProfile
SAML Identity Provider	SAML 2.0	pac4j-saml	Saml2Client	Saml2Profile

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. For example:

<dependency>
  <groupId>org.pac4j</groupId>
  <artifactId>pac4j-oauth</artifactId>
  <version>1.5.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, 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, 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, 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 Google and OpenID for authentication, you should use the org.pac4j.openid.client.GoogleOpenIdClient class:

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

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

// get the OpenID credentials
OpenIdCredentials credentials = client.getCredentials(context);
// get the GooglOpenID profile
GoogleOpenIdProfile 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 metadata 
client.setIdpMetadataPath("testshib-providers.xml");

// 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, 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);

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 googleOpenIdClient, 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

Integration library	Protocol(s) supported	Based on	Demo webapp
cas-server-support-pac4j 4.0.0-RC4	OAuth / CAS / OpenID	pac4j 1.4.1	cas-pac4-oauth-demo
cas-server-support-oauth 3.5.2	OAuth	scribe-up 1.2.0	cas-oauth-demo-3.5.x
play-pac4j 1.2.0 / 1.1.2	OAuth / CAS / OpenID / HTTP / SAML	pac4j 1.5.0	play-pac4j-java-demo play-pac4j-scala-demo
j2e-pac4j 1.0.2	OAuth / CAS / OpenID / HTTP / SAML	pac4j 1.5.0	j2e-pac4j-demo
buji-pac4j 1.2.2	OAuth / CAS / OpenID / HTTP / SAML	pac4j 1.5.0	buji-pac4j-demo
spring-security-pac4j 1.2.2	OAuth / CAS / OpenID / HTTP / SAML	pac4j 1.5.0	spring-security-pac4j-demo
ratpack 0.9.3	OAuth / CAS / OpenID / HTTP	pac4j 1.4.1	ratpack-pac4j-demo

Versions

The current version 1.5.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.5.0:

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

See the release notes.

Testing

pac4j is tested by more than 400 unit, bench and integration tests (authentication processes are completely simulated using the HtmlUnit library).

To launch the tests, the nr Maven profile should be used. For example:

mvn clean install -Pnr

Use the js Maven profile for Javadoc and sources generation.

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:

• pac4j users
• pac4j developers