Installation

Adding the dependency

SecureSocial is available from the Typesafe community repository. To include the module in your project add the following dependency to your Build.scala file:

"securesocial" %% "securesocial" % "2.0.12"

Next, add a resolver so sbt can locate the dependency. There are two locations:

Releases: http://repo.scala-sbt.org/scalasbt/sbt-plugin-releases.
Snapshots: http://repo.scala-sbt.org/scalasbt/sbt-plugin-snapshots.

Choose either depending on whether you'd like to use a stable release or test the latest changes. This is a sample Build.scala file using a stable release:

object ApplicationBuild extends Build {
    val appName         = "myapp"
    val appVersion      = "1.0"

    val appDependencies = Seq(
        "securesocial" %% "securesocial" % "2.0.12"
    )
    val main = PlayProject(appName, appVersion, appDependencies, mainLang = SCALA).settings(
      resolvers += Resolver.url("sbt-plugin-snapshots", url("http://repo.scala-sbt.org/scalasbt/sbt-plugin-releases/"))(Resolver.ivyStylePatterns)
    )
}

Make sure to set the mainLang to the main language of your application. Valid options are JAVA or SCALA.

If you'd like to use the master snapshot change it to:

val appDependencies = Seq(
    "securesocial" %% "securesocial" % "master-SNAPSHOT"
)
val main = play.Project(appName, appVersion, appDependencies).settings(
  resolvers += Resolver.url("sbt-plugin-snapshots", new URL("http://repo.scala-sbt.org/scalasbt/sbt-plugin-snapshots/"))(Resolver.ivyStylePatterns)
)

Note

Versions prior 2.0.11 are available at:

Releases: http://securesocial.ws/repository/releases.
Snapshots: http://securesocial.ws/repository/snapshots.

Adding routes

Add the routes for SecureSocial into your app's routes file:

# Login page
GET     /login                      securesocial.controllers.LoginPage.login
GET     /logout                     securesocial.controllers.LoginPage.logout

# User Registration and password handling 
GET     /signup                     securesocial.controllers.Registration.startSignUp
POST    /signup                     securesocial.controllers.Registration.handleStartSignUp
GET     /signup/:token              securesocial.controllers.Registration.signUp(token)
POST    /signup/:token              securesocial.controllers.Registration.handleSignUp(token)
GET     /reset                      securesocial.controllers.Registration.startResetPassword
POST    /reset                      securesocial.controllers.Registration.handleStartResetPassword
GET     /reset/:token               securesocial.controllers.Registration.resetPassword(token)
POST    /reset/:token               securesocial.controllers.Registration.handleResetPassword(token)
GET     /password                   securesocial.controllers.PasswordChange.page
POST    /password                   securesocial.controllers.PasswordChange.handlePasswordChange

# Providers entry points
GET     /authenticate/:provider     securesocial.controllers.ProviderController.authenticate(provider)
POST    /authenticate/:provider     securesocial.controllers.ProviderController.authenticateByPost(provider)
GET     /not-authorized             securesocial.controllers.ProviderController.notAuthorized

SecureSocial Plugins

SecureSocial is designed in a modular architecture using plugins. This means you can easily enable/disable them to include only what you need and also that you can change the built-in plugins for your own implementation if there is a need to customize how things work.

Plugins are defined in the play.plugins file under the conf directory. If you don't have that file yet create one and add:

1500:com.typesafe.plugin.CommonsMailerPlugin
9994:securesocial.core.DefaultAuthenticatorStore
9995:securesocial.core.DefaultIdGenerator
9996:securesocial.core.providers.utils.DefaultPasswordValidator
9997:securesocial.controllers.DefaultTemplatesPlugin
9998:your.user.Service.Implementation <-- Important: You need to change this
9999:securesocial.core.providers.utils.BCryptPasswordHasher
10000:securesocial.core.providers.TwitterProvider
10001:securesocial.core.providers.FacebookProvider
10002:securesocial.core.providers.GoogleProvider
10003:securesocial.core.providers.LinkedInProvider
10004:securesocial.core.providers.UsernamePasswordProvider
10005:securesocial.core.providers.GitHubProvider
10006:securesocial.core.providers.FoursquareProvider
10007:securesocial.core.providers.XingProvider
10008:securesocial.core.providers.VkProvider
10009:securesocial.core.providers.InstagramProvider

Only the authentication providers you include in the play.plugins file will appear on the login page.

If you don't plan to have a username and password login you can remove UsernamePasswordProvider, CommonsMailerPlugin, BCryptPasswordHasher and DefaultPasswordValidator.

Important

There is one plugin you need to write for your apps, and that is the UserService. The line that starts with 9998 above is just a place holder where you need to enter the class of your implentation. To start, you can copy the InMemoryUserService provided in the samples (Scala or Java) and then change it.