Updated documentation in preparation for the 2.0.8 release

Updated changelog

ChangeLog

@@ -1,7 +1,8 @@
 master
+		- PasswordHasher and Password validator are abstract classes instead of traits now (simplifies Java integration).
 		- Fixed: wrong LinkedIn key for getting fullName (thanks @chazmcgarvey).
 		- Removed servceInfo from OAuth1Info. That object can be retrieved from SecureSocial.serviceInfoFor method now.
-		- Breaking changes to the Java API: deleted AuthenticationMethod, OAuth1Info, OAuth2Info, PasswordInfo, SocialUser and UserId. This was required because after introducing the Identity trait I need to make sure the user gets its own object in the actions instead of a SocialUser instance.  Even though there's not a Java equivalent, the Scala classes can be called from Java easily.
+		- Backward incompatible changes to the Java API: deleted AuthenticationMethod, OAuth1Info, OAuth2Info, PasswordInfo, SocialUser and UserId. This was required because after introducing the Identity trait I need to make sure the user gets its own object in the actions instead of a SocialUser instance.  Even though there's not a Java equivalent, the Scala classes can be called from Java easily.
 		- Added new message to messages file: securesocial.login.errorLoggingIn
 		- Improved ProviderController.handleAuth to show an error if an error occurrs while logging the user in (eg: if the UserService.save implemewntation throws an exception)
 		- Fixed: Identity providers were filling wrong provider id values

docs/src/manual/data/guide.yml

@@ -3,6 +3,7 @@ sections:
    - { title: Installation, file: installation}
    - { title: Configuration, file: configuration}
    - { title: Securing your Actions, file: securing}
+   - { title: Adding Authorization, file: authorization}
    - { title: UserService, file: user-service}
    - { title: Views and Emails Customization, file: views-customization}
    - { title: Password Change Page, file: password-change }

docs/src/manual/data/versions.yml

@@ -1,2 +1,2 @@
-ss2: 2.0.6
+ss2: 2.0.8
 ss1: 0.2.6 

docs/src/manual/source/guide/authorization.md

@@ -0,0 +1,59 @@
+---
+file: authorization
+---
+# Adding Authorization
+
+SecureSocial provides a way to add authorization logic to your controller actions.  This is done by implementing an `Authorization` object that is passed to the `SecuredAction` as a parameter.
+
+After checking if a user is authenticated the `Authorization` instance is used to verify if the execution should be allowed or not.
+
+## Scala
+
+For Scala, you need to implement the `Authorization` trait.
+
+	:::scala
+	trait Authorization {		
+		def isAuthorized(user: Identity): Boolean
+	}
+
+This is a sample implementation that only grants acccess to users that logged in usign a given provider:
+
+	:::scala
+	case class WithProvider(provider: String) extends Authorization {
+	  def isAuthorized(user: Identity) = {
+	    user.id.providerId == provider
+	  }
+	}
+
+Here's how you would use it:
+
+	:::scala
+	def myAction = SecuredAction(WithProvider("twitter")) { implicit request =>
+		// do something here
+	}
+
+## Java
+
+For Java, you need to implement the `Authorization` interface.
+
+	:::java
+	public interface Authorization {
+ 	   boolean isAuthorized(Identity user, String[] params);
+	}
+
+This is an equivalent implementation to the Scala sample:
+
+	:::java
+	public class WithProvider implements Authorization {
+	    public boolean isAuthorized(Identity user, String params[]) {
+	        return user.id().providerId().equals(params[0]);
+	    }
+	}
+
+Here's how you would use it:
+
+	:::java
+	@SecureSocial.SecuredAction( authorization = WithProvider.class, params = {"twitter"})
+    public static Result myAction() {
+        // do something here
+    }

docs/src/manual/source/guide/changelog.md

@@ -5,6 +5,27 @@ file: changelog
 
 *This is the change log for the SecureSocial 2 version. Check the [1.x](https://github.com/jaliss/securesocial/tree/1.x) branch if you're interested in SecureSocial 1.*
 
+**2.0.8   - 2013-01-01**
+
+- PasswordHasher and Password validator are abstract classes instead of traits now (simplifies Java integration).
+- Fixed: wrong LinkedIn key for getting fullName (thanks @chazmcgarvey).
+- Removed serviceInfo from OAuth1Info. That object can be retrieved from SecureSocial.serviceInfoFor method now.
+- Backward incompatible changes to the Java API: deleted AuthenticationMethod, OAuth1Info, OAuth2Info, PasswordInfo, SocialUser and UserId. This was required because after introducing the Identity trait I needed to make sure the user received his own object in the actions instead of a SocialUser instance.  Even though there's not a Java equivalent, the Scala classes can be called from Java easily.
+- Added new message to messages file: securesocial.login.errorLoggingIn
+- Improved ProviderController.handleAuth to show an error if an error occurrs while logging the user in (eg: if the UserService.save implementation throws an exception)
+- Fixed: Identity providers were filling wrong provider id values
+- Added: UsernamePasswordProvider updates the user avatar if gravatar support is enabled now.
+- Added timeout for sessions (30 mins by default, use sessionTimeOut property to change).
+- Fixed: PasswordValidator was not being used in password reset
+- Fixed: When a token is expired the user is properly redirected to the sign up or reset pages now
+- Added enableTokenJob property to enable/disable the background job
+- Fixed method typo AuthenticationMethod: toScala.
+- Right http codes are returned for ajax calls now
+- New assetsController property to override the assets class in RoutesHelper. Needed when a custom Asset controller is used by the app.
+- Added hasher id to PasswordInfo
+- Added support for registering multiple PasswordHashers to allow upgrading the hashing algorithm.
+- Introduced Identity trait. SocialUser now implements it (this will allow developers to return their own user class from UserService.find methods)
+
 **2.0.7   - 2012-11-25**
 
 - Added password change functionality

docs/src/manual/source/guide/configuration.md

@@ -3,7 +3,10 @@ file: configuration
 ---
 # Configuration
 
-Create a `securesocial.conf` file within your app's conf directory.  Then include it from your `application.conf` file.  
+Create a `securesocial.conf` file within your app's conf directory and include it from your `application.conf` file.  Eg:
+
+	:::bash
+	include "securesocial.conf"
 
 ## Mail settings
 
@@ -21,17 +24,25 @@ These settings go in the `smtp` section of the `securesocial.conf` file:
 		from="your_from_address"
 	}
 
-## Redirection and SSL
+## Global Settings
 
-SecureSocial tries to redirect the user back to the page they intended to access after login.  There are cases where this can't be done (eg: the user tried to POST a form) or accessed the login page directly.  Adding the `onLoginGoto` property allows SecureSocial to redirect the user to the page you need.  There is also a `onLogoutGoto` property for logout actions.
+- `onLoginGoTo`: SecureSocial tries to redirect the user back to the page they intended to access after login.  There are cases where this can't be done (eg: the user tried to POST a form) or accessed the login page directly.  Adding the `onLoginGoto` property allows SecureSocial to redirect the user to the page you need.  
 
-You can enable SSL for OAuth callbacks and for the login, signup and reset password actions of the `UsernamePasswordProvider` (you'll want this in production mode).
+- `onLogoutGoTo`: The page where the user is redirected to after logging out.
 
-	:::bash
+- `ssl`: You can enable SSL for OAuth callbacks and for the login, signup and reset password actions of the `UsernamePasswordProvider` (you'll want this in production mode).
+
+- `sessionTimeOut`: Specifies the session time out in minutes. Users get logged out automatically after being inactive for the minutes specified in this property.  The default is 60 minutes.
+
+- `assetsController`: This setting is optional.  It is only needed if you are not using the default Assets controller provided by Play.  The value must be the full qualified class name of your controller prepended by the word Reverse.
+
+All these settings go inside a `securesocial` section as shown below:
+
+    :::bash    
 	securesocial {
 		#
 		# Where to redirect the user if SecureSocial can't figure that out from
-		# the request that led the use to the login page
+		# the request that was received before authenticating the user
 		#
 		onLoginGoTo=/
 
@@ -44,11 +55,23 @@ You can enable SSL for OAuth callbacks and for the login, signup and reset passw
 		# Enable SSL for oauth callback urls and login/signup/password recovery pages
 		#
 		ssl=false	
+
+		#
+		# Session Timeout In Minutes
+		#
+		sessionTimeOut=60
+
+		#
+		# The controller class for assets. This is optional, only required
+		# when you use a custom class for Assets.
+		#
+		assetsController=controllers.ReverseMyCustomAssetsController	       
 	}
 
+
 ## Provider settings
 
-The configuration for each provider goes within the `securesocial` section as well. 
+The configuration for each provider needs to be added within the `securesocial` section as well. 
 
 ### Username Passsword Provider
 
@@ -132,3 +155,9 @@ A configuration would like like:
 	}
 
 To get the `clientId`/`clientSecret` or `consumerKey`/`consumerSecret` keys you need to log into the developer site of each service (eg: Twitter, Facebook) and register your application.
+
+*Hint: you can use the `securesocial.conf` file in the sample apps as a starting point.*
+
+## Clustered environments
+
+SecureSocial uses the Play cache to store values while signing in users via OAuth.  If you have more than one server then make sure to use a distributed cache (eg: memcached).

docs/src/manual/source/guide/getting-started.html.md.erb

@@ -4,7 +4,7 @@ file: getting-started
 # Getting Started
 
 SecureSocial is an authentication module for Play Framework applications that works with
-services based on OAuth1, OAuth2 and OpenID.  
+services based on OAuth1, OAuth2 and OpenID*.  
 
 It provides out of the box support for:
 
@@ -15,7 +15,7 @@ It provides out of the box support for:
 - LinkedIn (OAuth1)
 - Username/Password with signup and reset password functionality.
 
-*More services are coming soon*
+**OpenID and more services are coming soon*
 
 # Scala or Java
 

docs/src/manual/source/guide/installation.html.md.erb

@@ -5,7 +5,7 @@ file: installation
 
 ### Adding the dependency
 
-SecureSocial is available as a downloadable dependency.  There is repository hosted on the project site with stable releases and snapshots.  To include the module in your project add the folling dependency to your `Build.scala` file:
+SecureSocial is available as a downloadable dependency.  There is a repository hosted on the project site with stable releases and snapshots.  To include the module in your project add the folling dependency to your `Build.scala` file:
 
 	:::scala
 	"securesocial" % "securesocial_2.9.1" % "<%= data.versions.ss2 %>"
@@ -52,7 +52,7 @@ Add the routes for SecureSocial into your app's `routes` file:
 	GET     /login                      securesocial.controllers.LoginPage.login
 	GET     /logout                     securesocial.controllers.LoginPage.logout
 
-	# User Registration and password handling (only needed if you are using UsernamePasswordProvider)
+	# 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)

docs/src/manual/source/guide/password-change.md

@@ -7,7 +7,7 @@ If you use the `UsernamePasswordProvider` you can add a change password page to
 
 ### Scala
 
-Assuming your template received a `user` parameter with an instance of `SocialUser` you would add a link to the Password Change page as follows:
+Assuming your template received a `user` parameter with an instance of `Identity` you would add a link to the Password Change page as follows:
 
 	:::html
 	@user.passwordInfo.map { info =>
@@ -24,15 +24,15 @@ Make sure to add the following import statement in your template:
 And add an implicit `RequestHeader` parameter to it too.  For example:
 
 	:::scala
-	@(user: securesocial.core.SocialUser)(implicit request: RequestHeader)
+	@(user: securesocial.core.Identity)(implicit request: RequestHeader)
 
 
 ### Java
 
-For Java applications the syntax is a little bit different.  Assuming your template received a `user` parameter with an instance of `SocialUser` you would add:
+For Java applications the syntax is a little bit different.  Assuming your template received a `user` parameter with an instance of `Identity` you would add:
 
  	:::html
- 	@if( user.passwordInfo != null ) {
+ 	@user.passwordInfo.map { info =>
         <a class="btn" href="@securesocial.core.providers.utils.RoutesHelper.changePasswordPage.absoluteURL(Implicit.request(), IdentityProvider.sslEnabled)">
         	Change Password
         </a>

docs/src/manual/source/guide/password-plugins.md

@@ -21,10 +21,10 @@ This will be good enough for many cases, but if you need to change the way passw
 
 ### Scala
 
-For Scala, you need to implement the `PasswordValidator` trait:
+For Scala, you need to extend the `PasswordValidator` class:
 
 	:::scala
-	trait PasswordValidator extends Plugin {
+	abstract class PasswordValidator extends Plugin {
 	  	def isValid(password: String): Boolean
 	  	def errorMessage: String
     }
@@ -37,7 +37,7 @@ You will also need to add a constructor that receives an `Application` instance.
 
 ### Java
 
-For Java, create a subclass of `BasePasswordValidator` and implement the `isValid` and `errorMessage` methods as described above and also add a public constructor that receives an `Application` instance.
+For Java, extend the `PasswordValidator` class and implement the `isValid` and `errorMessage` methods as described above and also add a public constructor that receives an `Application` instance.
 
     :::java
     public boolean isValid(String password)
@@ -47,23 +47,36 @@ For Java, create a subclass of `BasePasswordValidator` and implement the `isVali
 
 ### Scala
 
-For Scala, you need to implement the `PasswordHasher` trait:
+For Scala, extend the `PasswordHasher` class:
 
 	:::scala
-	trait PasswordHasher extends Plugin {
+	abstract class PasswordHasher extends Plugin with Registrable {
   		def hash(plainPassword: String): PasswordInfo
 		def matches(passwordInfo: PasswordInfo, suppliedPassword: String): Boolean
 	}
 
+- `id`: returns a `String` that identifies this hasher.
+
 - `hash`: this method hashes the password and returns a `PasswordInfo` containing the hashed password and optionally the salt used to hash it.
 
 - `matches`: checks if the `suppliedPassword` matches the hashed one in `passwordInfo`.
 
 ### Java
 
-For Java, extend the `BasePasswordHasher` class and implement the `doHash` and `doMatch` mathods:
+For Java, extend the `PasswordHasher` class and implement the `id`, `hash` and `match` mathods:
 
 	:::java	
-   	PasswordInfo doHash(String plainPassword);    
-    boolean doMatch(PasswordInfo passwordInfo, String suppliedPassword);
+	public String id()
+   	public PasswordInfo hash(String plainPassword)
+ 	public boolean matches(PasswordInfo passwordInfo, String suppliedPassword)
+
+The `PasswordInfo` object is defined in Scala.  To create an instance can do do something like:
+
+	:::java	
+	// to create one with a salt
+	PasswordInfo info = new PasswordInfo("my_hasher", "hashed_password_here", Scala.Option("some_salt"));
+
+	// to create one without a salt
+	PasswordInfo info = new PasswordInfo("my_hasher", "hashed_password_here", Scala.<String>Option(null));
+