Migration Guide

The new Silhouette 4.0 version depends on Play 2.5. So please visit the Play 2.5 Migration Guide for more information.

🚧

Info

If you migrate from version 2.0 to 3.0 please refer to the 3.0 migration guide.

Project structure

Some parts of the project were packed into separate sub-projects. The code is still contained in the main repository, but now the dependencies must be included additionally to the main Silhouette package.

Password Hasher

The default BCryptPasswordHasher implementation has an extra dependency to the jBCrypt library. To limit the dependencies for future password hashing algorithms, we made the decision to split up this package.

To use the package you must include the additional dependency into your project:

libraryDependencies ++= Seq(
  "com.mohiva" %% "play-silhouette-password-bcrypt" % "4.0.0"
)

Persistence Layer

Since the beginning of Silhouette, an example implementation of a persistence layer is contained in the project. For some people this was confusing because Silhouette itself has a very low coupling to the persistence layer and so it was not clear which classes must be used and which not. The new structure makes it now clear that the persistence layer provided by Silhouette is an addition to the Silhouette core.

To use the example package you must include the additional dependency into your project; note that you will probably need to replace this dependency with your own custom code for production:

libraryDependencies ++= Seq(
  "com.mohiva" %% "play-silhouette-persistence" % "4.0.0"
)

libraryDependencies ++= Seq(
  "com.mohiva" %% "play-silhouette-persistence-reactivemongo" % "4.0.0-RC1"
)

The source code for the MongoDB based persistence layer can be found in the following GitHub repository.

https://github.com/mohiva/play-silhouette-persistence-reactivemongo

Environment

In the previous version of Silhouette it was necessary to define the Identity and Authenticator for every Environment declaration. This has lead to a lot of boilerplate code and it made it hard to refactor the code if e.g. the authenticator implementation was changed. Therefore we have introduced the Environment type.

Endpoints

The biggest change in Silhouette 4.0 is the fact that RequestHandlers and Actions are now injected into controllers instead of inheriting the Silhouette trait. Injecting the components is now the preferred method from Play 2.5 on. Silhouette makes this very easy by providing the Silhouette stack, which contains the Environment and all the available RequestHandlers and Actions.

So instead of a controller declaration in Silhouette 3.0:

class MyController @Inject() (
  val messagesApi: MessagesApi,
  val env: Environment[User, CookieAuthenticator])
  extends Silhouette[User, CookieAuthenticator] {

  def index = SecuredAction { implicit request =>
    Ok(views.html.index(request.identity))
  }
}

The new declaration has changed to:

class MyController @Inject() (silhouette: Silhouette[MyEnv]) extends Controller {
  
  def index = silhouette.SecuredAction { implicit request =>
    Ok(views.html.index(request.identity))
  }
}

Error handlers

The SecuredErrorHandler has been removed in favor of injectable error handlers. Please visit the documentation for more details.

Authenticator

The header based authenticators now have an additional configuration property which allows to define in which parts of the request the token can be transferred. Previously the token could only be transferred in the header. Now it's possible to transfer it in multiple parts of the request. The allowed types can be found in the RequestExtractor implementation. Please see the Authenticators configuration for more information.

Authorization

The Messages parameter has been removed from the isAuthorized method. Instead you should now use the I18nSupport trait provided by Play to get the Messages from the provided Request.

Events

The Messages parameter has been removed from all the provided SilhouetteEvent implementations. Instead you should now use the I18nSupport trait provided by Play to get the Messages from the provided RequestHeader.

Providers

Social profile builders and parsers

The signature of the SocialProfileParser.parse method has slightly changed. It gets now the auth info passed so that parser can query the provider API again to retrieve additional data.

API URL

For the OAuth1 and OAuth2 based providers it's now possible to override the hardcoded API URL which is used to fetch the profile information from the API. For this we have added an additional apiURL field to the OAuth1Settings and the OAuth2Settings classes. This field is optional and has the default value None.

Providers which depends on the PasswordHasher

The BasicAuthProvider and the CredentialsProvider now use the PasswordHasherRegistry to define the password hashers for an application. The password hasher registry defines the current password hasher which is able to hash all new passwords and also match the passwords stored in the backing store for this algorithm. And also a list of deprecated hashers, which should match passwords that are stored in the baking store but which are different to the current hasher.

This solution defines now unambiguous when a password hasher or a password is deprecated and when it should be updated with a newer algorithm.