hersoncruz / play-pac4j Goto Github PK

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

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

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

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.

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-SNAPSHOT"
)

Or the play-pac4j_scala dependency for a Scala application.

As it's a snapshot 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.

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

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("http://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("http://localhost:9000/casProxyCallback");
  casClient.setCasProxyReceptor(casProxyReceptor);*/
  casClient.setCasLoginUrl("http://localhost:8080/cas/login");
  
  final Clients clients = new Clients("http://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).

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.

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)
}

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()

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

The current version 1.3.0-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.2.1 version:

<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>play-pac4j_java</artifactId> or <artifactId>play-pac4j_scala</artifactId>
    <version>1.2.1</version>
</dependency>

See the release notes.

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

• pac4j users
• pac4j developers