README.md

What is the play-pac4j library ?

The play-pac4j library is a Java and Scala multi-protocols client for Play framework 2.x.

It supports 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.

It's available under the Apache 2 license and based on my pac4j library.

Play framework/ Language	Java	Scala
Play 2.0	play-pac4j_java v1.1.x	play-pac4j_scala2.9 v1.1.x
Play 2.1	play-pac4j_java v1.1.x	play-pac4j_scala2.10 v1.1.x
Play 2.2	play-pac4j_java v1.2.x	play-pac4j_scala v1.2.x
Play 2.3	play-pac4j_java v1.3.x	play-pac4j_scala2.10 and play-pac4j_scala2.11 v1.3.x

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
ORCiD	OAuth 2.0	pac4j-oauth	OrcidClient	OrcidProfile
Web sites with basic auth authentication	HTTP	pac4j-http	BasicAuthClient	HttpProfile
Web sites with form authentication	HTTP	pac4j-http	FormClient	HttpProfile
Google - Deprecated	OpenID	pac4j-openid	GoogleOpenIdClient	GoogleOpenIdProfile
Yahoo	OpenID	pac4j-openid	YahooOpenIdClient	YahooOpenIdProfile
SAML Identity Provider	SAML 2.0	pac4j-saml	Saml2Client	Saml2Profile
Google App Engine User Service	Gae User Service Mechanism	pac4j-gae	GaeUserServiceClient	GaeUserServiceProfile

Technical description

This library has just 11 classes:

• the Config class gathers all the configuration
• the Constants class gathers all the constants
• the CallbackController class is used to finish the authentication process and logout the user
• the StorageHelper class deals with storing/retrieving data from the cache
• the JavaWebContext class is a Java wrapper for the user request, response and session
• the JavaController class is the Java controller to retrieve the user profile or the redirection url to start the authentication process
• the RequiresAuthentication annotation is to protect an action if the user is not authenticated and starts the authentication process if necessary
• the RequiresAuthenticationAction class is the action to check if the user is not authenticated and starts the authentication process if necessary
• the ScalaController trait is the Scala controller to retrieve the user profile or the redirection url to start the authentication process
• the ScalaWebContext class is a Scala wrapper for the user request, response and session
• the PlayLogoutHandler class is dedicated to CAS support to handle CAS logout request.

and is based on the pac4j-* libraries.

Learn more by browsing the play-pac4j Javadoc and the pac4j Javadoc.

How to use it ?

Add the required dependencies

First, the dependency on play-pac4j_java must be defined in the build.sbt file for a Java application:

libraryDependencies ++= Seq(
  "org.pac4j" % "play-pac4j_java" % "1.3.0"
)

Or the play-pac4j_scala2.10 or play-pac4j_scala2.11 dependency for a Scala application.

For snapshots that are only available in the Sonatype snapshots repository, the appropriate resolver must also be defined in the build.sbt file:

resolvers ++= Seq(
  "Sonatype snapshots repository" at "https://oss.sonatype.org/content/repositories/snapshots/"
)

If you want to use a specific client support, you need to add the appropriate dependency:

1. for OAuth support, the pac4j-oauth dependency is required
2. for CAS support, the pac4j-cas dependency is required
3. for HTTP support, the pac4j-http dependency is required
4. for OpenID support, the pac4j-openid dependency is required.
5. for SAML 2.0 support, the pac4j-saml dependency is required
6. for Google App Engine, the pac4j-gae dependency is required.

    libraryDependencies ++= Seq(
      "org.pac4j" % "pac4j-http" % "1.6.0",
      "org.pac4j" % "pac4j-cas" % "1.6.0",
      "org.pac4j" % "pac4j-openid" % "1.6.0",
      "org.pac4j" % "pac4j-oauth" % "1.6.0",
      "org.pac4j" % "pac4j-saml" % "1.6.0",
      "org.pac4j" % "pac4j-gae" % "1.6.0"
    )

Define the supported clients

To use client support, your application must inherit from the JavaController class for a Java application:

public class Application extends JavaController {

or from the ScalaController trait for a Scala application:

object Application extends ScalaController {

You must define all the clients you want to support in the onStart method of your Global class for your Java or Scala application:

public void onStart(final Application app) {
  // OAuth
  final FacebookClient facebookClient = new FacebookClient("fb_key", "fb_secret");
  final TwitterClient twitterClient = new TwitterClient("tw_key", "tw_secret");
  // HTTP
  final FormClient formClient = new FormClient("https://localhost:9000/theForm", new SimpleTestUsernamePasswordAuthenticator());
  final BasicAuthClient basicAuthClient = new BasicAuthClient(new SimpleTestUsernamePasswordAuthenticator());
  // CAS
  final CasClient casClient = new CasClient();
  // casClient.setLogoutHandler(new PlayLogoutHandler());
  // casClient.setCasProtocol(CasProtocol.SAML);
  // casClient.setGateway(true);
  /*final CasProxyReceptor casProxyReceptor = new CasProxyReceptor();
  casProxyReceptor.setCallbackUrl("https://localhost:9000/casProxyCallback");
  casClient.setCasProxyReceptor(casProxyReceptor);*/
  casClient.setCasLoginUrl("https://localhost:8080/cas/login");
  
  final Clients clients = new Clients("https://localhost:9000/callback", facebookClient, twitterClient, formClient, basicAuthClient, casClient); // , casProxyReceptor);
  Config.setClients(clients);
}

The /callback url is the callback url where the providers (Facebook, Twitter, CAS...) redirects the user after successfull authentication (with the appropriate credentials).

Get user profiles and protect actions

You can get the profile of the (authenticated) user in a Java application by using the getUserProfile() method:

public static Result index() {
  // profile (maybe null if not authenticated)
  final CommonProfile profile = getUserProfile();
  return ok(views.html.index.render(profile));
}

And protect the access of a specific url by using the RequiresAuthentication annotation:

@RequiresAuthentication(clientName = "FacebookClient")
public static Result protectedIndex() {
  // profile
  final CommonProfile profile = getUserProfile();
  return ok(views.html.protectedIndex.render(profile));
}

Or you can get the profile of the (authenticated) user in a Scala application by using the getUserProfile(request) method:

def index = Action { request =>
  val profile = getUserProfile(request)
  Ok(views.html.index(profile))
}

And protect the access of a specific url by using the RequiresAuthentication function:

def protectedIndex = RequiresAuthentication("FacebookClient") { profile =>
  Action { request =>
    Ok(views.html.protectedIndex(profile))
  }
}

After successfull authentication, the originally requested url is restored.

Get redirection urls

You can also explicitely compute a redirection url to a provider for authentication by using the getRedirectionUrl method for a Java application:

public static Result index() {
  final String url = getRedirectionUrl("TwitterClient", "/targetUrl");
  return ok(views.html.index.render(url));
}

Or in a Scala application (always call the getOrCreateSessionId(request) method first):

def index = Action { request =>
  val newSession = getOrCreateSessionId(request)
  val url = getRedirectionUrl(request, newSession, "FacebookClient", "/targetUrl")
  Ok(views.html.index(url)).withSession(newSession)
}

Define the callback url

The callback url must be defined in the routes file as well as the logout:

GET   /                       controllers.Application.index()
GET   /protected/index.html   controllers.Application.protectedIndex()
GET   /callback               org.pac4j.play.CallbackController.callback()
POST  /callback               org.pac4j.play.CallbackController.callback()
GET   /logout                 org.pac4j.play.CallbackController.logoutAndRedirect()

Use the appropriate profile

From the CommonProfile, you can retrieve the most common properties that all profiles share. But you can also cast the user profile to the appropriate profile according to the provider used for authentication. For example, after a Facebook authentication:

// facebook profile
FacebookProfile facebookProfile = (FacebookProfile) commonProfile;

Or for all the OAuth profiles, to get the access token:

OAuthProfile oauthProfile = (OAuthProfile) commonProfile
String accessToken = oauthProfile.getAccessToken();
// or
String accessToken = facebookProfile.getAccessToken();</code></pre>

Demos

Demos with Facebook, Twitter, CAS, form authentication and basic auth authentication providers are available at:

1. play-pac4j-java-demo for Java applications
2. play-pac4j-scala-demo for Scala applications.

Versions

The current version 1.3.1-SNAPSHOT is under development. It's available on the Sonatype snapshots repository as a Maven dependency:

The latest release of the play-pac4j project is the 1.3.0 version:

<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>play-pac4j_java</artifactId> or <artifactId>play-pac4j_scala2.10</artifactId> or <artifactId>play-pac4j_scala2.11</artifactId>
    <version>1.3.0</version>
</dependency>

See the release notes.

Contact

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

• pac4j users
• pac4j developers