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.