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.4"
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.4"
)
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")
)
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:
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 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.
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.