Installation

Adding the dependency

SecureSocial is available from Maven Central. To include the module in your project add the following dependency to your Build.scala or build.sbt file:

"ws.securesocial" %% "securesocial" % "2.1.3"

Next, add the Sonatype Resolver so sbt can locate the dependency. For example, a Build.scala file would look like:

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

    val appDependencies = Seq(
        "ws.securesocial" %% "securesocial" % "2.1.3"
    )
    val main = play.Project(appName, appVersion, appDependencies).settings(
        resolvers += Resolver.sonatypeRepo("releases")
    )
}

If you'd like to use the master snapshot instead of a stable release change it to:

val appDependencies = Seq(
    "ws.securesocial" %% "securesocial" % "master-SNAPSHOT"
)
val main = play.Project(appName, appVersion, appDependencies).settings(
  resolvers += Resolver.sonatypeRepo("snapshots")
)

Previous releases

If you need to use a version older than 2.1.3 specify the dependency as:

 "securesocial" %% "securesocial" % "desired_version_here"

Since previous releases were not hosted in Maven one of the following resolvers need to be used:

Versions 2.0.11 to 2.1.2

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

Versions prior 2.0.11

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