authlogic_rpx 1.0.4 → 1.1.0

data/CHANGELOG.rdoc

@@ -1,3 +1,13 @@
+== 1.1.0 released 2010-01-05
+
+* added identity mapping and merging support  [GH#10,GH#13]
+  * new configuration parameters: account_mapping_mode; account_merge_enabled.
+  * new callbacks: before_merge_rpx_data; after_merge_rpx_data. 
+* updated gem support to authlogic 2.1.3 and rpx_now 0.6.11
+* support all rpx_now options in popup/embed code [GH#6]
+* automated tests are now working [GH#7]
+* documentation updates
+
 == 1.0.4 released 2009-10-10
 
 * added new hooks for profile mapping (Session.map_rpx_data_each_login, ActsAsAuthentic.map_added_rpx_data) based on suggestion by trosser (github issue #5)

data/Manifest

@@ -4,17 +4,34 @@ Manifest
 README.rdoc
 Rakefile
 authlogic_rpx.gemspec
+generators/add_authlogic_rpx_migration/USAGE
+generators/add_authlogic_rpx_migration/add_authlogic_rpx_migration_generator.rb
+generators/add_authlogic_rpx_migration/templates/migration_internal_mapping.rb
+generators/add_authlogic_rpx_migration/templates/migration_no_mapping.rb
 init.rb
 lib/authlogic_rpx.rb
 lib/authlogic_rpx/acts_as_authentic.rb
 lib/authlogic_rpx/helper.rb
+lib/authlogic_rpx/rpx_identifier.rb
 lib/authlogic_rpx/session.rb
 lib/authlogic_rpx/version.rb
 rails/init.rb
-test/acts_as_authentic_test.rb
+test/fixtures/rpxresponses.yml
 test/fixtures/users.yml
+test/integration/basic_authentication_and_registration_test.rb
+test/integration/internal_mapping/basic_authentication_and_registration_test.rb
+test/integration/internal_mapping/settings_test.rb
+test/integration/no_mapping/basic_authentication_and_registration_test.rb
+test/integration/no_mapping/settings_test.rb
+test/libs/ext_test_unit.rb
+test/libs/mock_rpx_now.rb
 test/libs/rails_trickery.rb
+test/libs/rpxresponse.rb
 test/libs/user.rb
 test/libs/user_session.rb
-test/session_test.rb
 test/test_helper.rb
+test/test_internal_mapping_helper.rb
+test/unit/acts_as_authentic_settings_test.rb
+test/unit/session_settings_test.rb
+test/unit/session_validation_test.rb
+test/unit/verify_rpx_mock_test.rb

data/README.rdoc

@@ -1,14 +1,15 @@
-= Authlogic RPX
+= Authlogic_RPX
 
 == Purpose
 
-Authlogic RPX is an Authlogic extension library that provides support for authentication using the RPX multi-authentication service offered by JanRain. To use RPX, you must first register your application at {RPX}[http://rpxnow.com/]. A free "Basic" account is available, in addition to paid enhanced versions. All work with Authlogic_RPX.  
+Authlogic_RPX is an Authlogic extension library that provides support for authentication using the RPX multi-authentication service offered by JanRain. To use RPX, you must first register your application at {RPX}[http://rpxnow.com/]. A free "Basic" account is available, in addition to paid enhanced versions. All work with Authlogic_RPX.  
 
 Key features and capabilities:
 * Auto-registration by default following RPX authentication (can be disabled if required)
 * Can allow users to enable RPX authentication for their existing password-enabled accounts
 * View helpers to assist with inserting login fragments in pages
 * Can co-exist with standard password authentication
+* Supports identity mapping and merging (allowing users to have multiple logins associated with one member record on your site)
 
 
 == Authlogic_RPX References
@@ -29,14 +30,14 @@ The demonstration Rails application is where you can see Authlogic_RPX in action
 *	<b>RPX_now gem repo:</b> [http://github.com/grosser/rpx_now]
 
 
-== Installing Authlogic RPX gem
+== Installing Authlogic_RPX gem
 
-Three gems are required: authlogic, grosser-rpx_now, and authlogic_rpx. Install these as appropriate to your environment and preferences.
+Three gems are required: authlogic, rpx_now, and authlogic_rpx. Install these as appropriate to your environment and preferences.
 
 Currently tested versions:
-* authlogic 2.1.2,2.1.1
-* rpx_now 0.6.6
-* authlogic_rpx 1.0.4
+* authlogic 2.1.3,2.1.2,2.1.1
+* rpx_now 0.6.11,0.6.6
+* authlogic_rpx 1.1.0
 
 
 === 1. Direct gem installation
@@ -50,9 +51,9 @@ Currently tested versions:
 
 Include in config/environment.rb:
   
-  config.gem 'authlogic', :version => '>= 2.1.1'
-  config.gem 'rpx_now', :version => '>= 0.6.6', :source => 'http://gemcutter.org'
-  config.gem 'authlogic_rpx', :version => '>= 1.0.4', :source => 'http://gemcutter.org'
+  config.gem 'authlogic', :version => '>= 2.1.3'
+  config.gem 'rpx_now', :version => '>= 0.6.11', :source => 'http://gemcutter.org'
+  config.gem 'authlogic_rpx', :version => '>= 1.1.0', :source => 'http://gemcutter.org'
 
 Then to install, run from the command line:
 
@@ -63,20 +64,69 @@ Then to install, run from the command line:
 
 Include in RAILS_ROOT/.gems:
   
-  authlogic --version '>= 2.1.1'
-  rpx_now --version '>= 0.6.6' --source gemcutter.org
-  authlogic_rpx --version '>= 1.0.4' --source gemcutter.org
+  authlogic --version '>= 2.1.3'
+  rpx_now --version '>= 0.6.11' --source gemcutter.org
+  authlogic_rpx --version '>= 1.1.0' --source gemcutter.org
 
 
-== Using Authlogic RPX
+== About Authlogic_RPX
 
-<i>Note: in what follows, the user model is called User and the session controller takes the name UserSession (the authlogic convention). You are not restricted to these names - could be Member and MemberSession for example - but for simplicity, this documentation will stick to using the "User" convention.</i>
-
-Using Authlogic RPX is very similar to using standard authlogic, with the addition of just a few configuration options. So if you already have a project setup with authlogic, adding RPX support will be trivial.
+Using Authlogic_RPX is very similar to using standard authlogic, with the addition of just a few configuration options. So if you already have a project setup with authlogic, adding RPX support will be trivial.
 
 An important capability to be aware of is "auto registration". This means that when a user has logged in with RPX, if an account does not already exist in your application, it will be automatically created. That is, there is no separate/special "register" step for users to go through before just signing in. You can disable this if you need, but for most sites that use RPX as a primary authentication mechanism, this is probably what you want to happen.
 
-The main steps for enabling Authlogic RPX: 
+One of the main limitations of Authlogic_RPX versions up to 1.0.4 was that it did not include any specific support for identity mapping. This means that if a user signs in with twitter one day, and facebook the next, then your application would see these as tow distinct users (NB: RPX provides some protection for this by trying to remember the last authentication method your users used. It's not always perfect however).
+
+From Authlogic_RPX version 1.1.0 we have added built-in identity mapping and merging support. This is what we call 'internal' mapping. The legacy approach from 1.0.4 and earlier is still supported as an option. This mapping mode is called 'none'.
+
+The JanRain RPXnow service has its own identity mapping implementation, but only available for paid accounts. This is still not supported directly by Authlogic_RPX, but is something we'd like to get into a future version.
+
+=== Chosing Your Mapping Mode
+
+When you configure Authlogic_RPX, you will need to decide which mapping mode to use.
+
+The options are:
+* :none - will use legacy/1.0.4 identity management with no mapping support. RPX identifiers are stored as a new attribute of your User model
+* :internal - uses Authlogic_RPX-based mapping. RPX identifiers are stored in a new model called RPXIdentifier. This model is completely private to Authlogic_RPX and you will not need to code anything specifically for it.
+* :rpxnow - currently not implemented; reserved for future use
+
+
+==== Upgrading from Authlogic_RPX 1.0.4 or earlier
+
+In Authlogic_RPX v1.0.4 and earlier, the rpx_identifier was stored in the user model, and identity mapping was not supported.
+
+If you are upgrading to 1.1.0 or later and wish to start using internal mapping:
+* Use the add_authlogic_rpx_migration generator to create the migration to support the new RPXIdentifiers model 
+* It is NOT necessary to migrate the rpx_identifiers.
+* DO NOT remove the legacy rpx_identifier column from your existing user model. The Authlogic_RPX code will migrate users to the new database structure as and when they login.
+* You may wish to explicitly set account_mapping_mode to :internal in the User model (it saves a few cycles over the default :auto). 
+
+e.g.
+
+  class User < ActiveRecord::Base
+    acts_as_authentic do |c|
+      c.account_mapping_mode :internal
+    end
+  end
+
+If you are upgrading to 1.1.0 or later and wish to continue using the legacy/1.0.4 approach (i.e. no mapping):
+* You will already have the rpx_identifier in your user model. DO NOT create any new migrations.
+* Just upgrade the gem and all should continue to work as before
+* You may wish to explicitly set account_mapping_mode to :none in the User model (it saves a few cycles over the default :auto). 
+
+e.g.
+
+  class User < ActiveRecord::Base
+    acts_as_authentic do |c|
+      c.account_mapping_mode :none
+    end
+  end
+
+== The Step-by-Step Guide to Using Authlogic_RPX
+
+<i>Note: in what follows, the user model is called User and the session controller takes the name UserSession (the authlogic convention). You are not restricted to these names - could be Member and MemberSession for example - but for simplicity, this documentation will stick to using the "User" convention.</i>
+
+The main steps for enabling Authlogic_RPX: 
 * 1. Enable RPX for your user model
 * 2. Add RPX configuration for the Authlogic session model
 * 3. Add custom user profile mapping (optional)
@@ -85,46 +135,153 @@ The main steps for enabling Authlogic RPX:
 * 6. Setup the Authlogic user controller
 * 7. Use view helpers to provide login links
 * 8. Allow users to "Add RPX" to existing accounts (optional)
+* 9. Customise Account Merge Behaviour (optional)
 
 
 === 1. Enable RPX for your user model
 
-The user model requires an additional field called "rpx_identifier". Creat a migration to add this. 
-You may need to remove database constraints on other fields if they will be unused in the RPX case (e.g. crypted_password and password_salt to make password authentication optional).
+The user model will have a has_many relationship with a new model, called RPXIdentifier. 
+A generator is provider to create the necessary migration:
 
-If you are using auto-registration, you must also remove any database constraints for fields that will be automatically mapped (see notes in "3. Add custom user profile mapping during auto-registration")
+  ruby script/generate add_authlogic_rpx_migration [mapping:mapping_mode] [user_model:model_name] 
+  
+The generator takes two optional parameters: mapping and user_model.
 
-  class AddUsersRpxIdentifier < ActiveRecord::Migration
-    def self.up
-      add_column :users, :rpx_identifier, :string
-      add_index :users, :rpx_identifier
+The mapping_mode parameter indicates which style of Authlogic_RPX-supported identity mapping should be used. The default mapping_mode is 'internal' Allowed values for mapping_mode are:
+* none (disables authlogic_rpx identity mapping. This is the same behaviour as in authlogic_rpx version 1.0.4 and earlier)
+* internal (enables authlogic_rpx internal identity mapping. This behaviour was introduced in version 1.1.0)
+
+The user_model parameter specifies the name of the user/member model in your application. The default model_name is 'User'. e.g. to generate the RPX migration where the user model is called 'Member' and you do not want to support identity mapping:
+    
+  ruby script/generate add_authlogic_rpx_migration mapping:none user_model:member
+    
+You may need to customise the migration file to remove database constraints on other fields if they will be unused in the RPX case
+(e.g. crypted_password and password_salt to make password authentication optional).
 
-      change_column :users, :crypted_password, :string, :default => nil, :null => true
-      change_column :users, :password_salt, :string, :default => nil, :null => true
+If you are using auto-registration, you must also remove any database constraints for fields that will be automatically mapped
+(see notes in "3. Add custom user profile mapping during auto-registration")
+
+==== Sample Migration Generated Script (using internal mapping)
+
+The following command will generate a migration for the case where you want to use authlogic_rpx internal mapping and your user model is called 'User':
+
+  ruby script/generate add_authlogic_rpx_migration mapping:internal user_model:user
+ 
+The migration script will appear like this:
+
+  class AddAuthlogicRpxMigration < ActiveRecord::Migration
+    def self.up
+      create_table :rpx_identifiers do |t|
+        t.string  :identifier, :null => false
+        t.string  :provider_name
+        t.integer :user_id, :null => false
+        t.timestamps
+      end
+      add_index :rpx_identifiers, :identifier, :unique => true, :null => false
+      add_index :rpx_identifiers, :user_id, :unique => false, :null => false
+      
+      # == Customisation may be required here ==
+      # You may need to remove database constraints on other fields if they will be unused in the RPX case
+      # (e.g. crypted_password and password_salt to make password authentication optional). 
+      # If you are using auto-registration, you must also remove any database constraints for fields that will be automatically mapped
+      # e.g.:
+      #change_column :users, :crypted_password, :string, :default => nil, :null => true
+      #change_column :users, :password_salt, :string, :default => nil, :null => true
       
     end
-
+    
     def self.down
-      remove_column :users, :openid_identifier
+      drop_table :rpx_identifiers
+      
+      # == Customisation may be required here ==
+      # Restore user model database constraints as appropriate
+      # e.g.:
+      #[:crypted_password, :password_salt].each do |field|
+      #  User.all(:conditions => "#{field} is NULL").each { |user| user.update_attribute(field, "") if user.send(field).nil? }
+      #  change_column :users, field, :string, :default => "", :null => false
+      #end
+  
+    end
+  end
 
-      [:crypted_password, :password_salt].each do |field|
-        User.all(:conditions => "#{field} is NULL").each { |user| user.update_attribute(field, "") if user.send(field).nil? }
-        change_column :users, field, :string, :default => "", :null => false
-      end
+{See the source for the sample 20091227051253_add_authlogic_rpx_migration.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/db/migrate/20091227051253_add_authlogic_rpx_migration.rb].
+
+==== Sample Migration Generated Script (using no mapping)
+
+The following command will generate a migration for the case where you don't want to use authlogic_rpx mapping and your user model is called 'Member':
+
+  ruby script/generate add_authlogic_rpx_migration mapping:none user_model:member
+ 
+The migration script will appear like this:
+
+  class AddAuthlogicRpxMigration < ActiveRecord::Migration
+  
+    def self.up
+      add_column :members, :rpx_identifier, :string
+      add_index :members, :rpx_identifier
+  
+      # == Customisation may be required here ==
+      # You may need to remove database constraints on other fields if they will be unused in the RPX case
+      # (e.g. crypted_password and password_salt to make password authentication optional).
+      # If you are using auto-registration, you must also remove any database constraints for fields that will be automatically mapped
+  
+      # e.g.:
+      #change_column :members, :crypted_password, :string, :default => nil, :null => true
+      #change_column :members, :password_salt, :string, :default => nil, :null => true
+  
     end
+  
+    def self.down
+      remove_column :members, :rpx_identifier
+  
+      # == Customisation may be required here ==
+      # Restore user model database constraints as appropriate
+      # e.g.:
+      #[:crypted_password, :password_salt].each do |field|
+      #  Member.all(:conditions => "#{field} is NULL").each { |user| user.update_attribute(field, "") if user.send(field).nil? }
+      #  change_column :members, field, :string, :default => "", :null => false
+      #end
+  
+    end
+  end
+
+==== Configuring the User model
+
+The user model then needs to be tagged with "acts_as_authentic". This is the minimal configuration:
+
+  class User < ActiveRecord::Base
+    acts_as_authentic
   end
 
-The user model then needs to be tagged with "acts_as_authentic", and you must add rpx_identifier to the attr_accessible configuration (if you are using it)
+Two RPX-specific user configuration options are available.
+* account_merge_enabled: true/false. Enables/disables user auto-registration (disabled by default)
+* account_mapping_mode: :auto/:none/:internal. Sets the Authlogic_RPX identity mapping mode (:auto by default)
+
+The account_mapping_mode options are defined as follows:
+* :auto - will select the correct mapping mode based on the table structures you have provisioned in the application
+* :none - will use legacy/1.0.4 identity management with no mapping support. RPX identifiers are stored as a new attribute of your User model
+* :internal - uses Authlogic_RPX-based mapping. RPX identifiers are stored in a new model called RPXIdentifier. This model is completely private to Authlogic_RPX and you will not need to code anything specifically for it.
+* :rpxnow - currently not implemented; reserved for future use.
+
+For example, the following shows how to set standard Authlogic configurations (validations_scope), enables RPX account merging, and specifies :internal account mapping:
 
   class User < ActiveRecord::Base
     acts_as_authentic do |c|
-      c.my_config_option = my_value # for available options see documentation in: Authlogic::ActsAsAuthentic
+      c.validations_scope = :company_id # for available Authlogic options see documentation in the various Config modules of Authlogic::ActsAsAuthentic
+      
+      # enable Authlogic_RPX account merging (false by default, if this statement is not present)
+      c.account_merge_enabled true
+      
+      # set Authlogic_RPX account mapping mode
+      c.account_mapping_mode :internal
+      
     end # block optional
-    attr_accessible :username, :email, :password, :password_confirmation, :rpx_identifier
+
   end
 
 {See the source for the sample user.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user.rb].
 
+NB: The RPXIdentifier model is included in the authlogic_rpx gem and does not need to be added to your project.
 
 === 2. Add RPX configuration for the Authlogic session model
 
@@ -168,7 +325,7 @@ Authlogic_rpx provides three hooks for mapping information from the RPX profile
  
 See https://rpxnow.com/docs#profile_data for the definition of available attributes in the RPX profile.
 
-=== 3a. map_rpx_data: user profile mapping during auto-registration
+==== 3a. map_rpx_data: user profile mapping during auto-registration
 
 When users auto-register, profile data from RPX is available to be inserted in the user's record on your site. By default, authlogic_rpx will map the username and email fields.
 
@@ -193,13 +350,12 @@ If you have other fields you want to map, you can provide your own implementatio
       self.attempted_record.fullname = @rpx_data['profile']['displayName'] if attempted_record.fullname.blank?
     
     	if rpx_extended_info?
-    		# map some extended attributes
+        # map some extended attributes
     	end
     end
   	
   end
 
-{See the source for the sample user_session.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user_session.rb].
 
 WARNING: if you are using auto-registration, any fields you map should NOT have constraints enforced at the database level.
 Authlogic_rpx will optimistically attempt to save the user record during registration, and violating a database constraint will cause the authentication/registration to fail.
@@ -216,6 +372,7 @@ If it is not acceptable in your application to have user records created with po
 * automatically "uniquify" certain fields like username
 * save conflicting profile information to "pending user review" columns or a seperate table
 
+{See the source for the sample user_session.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user_session.rb].
 
 ==== 3b. map_rpx_data_each_login: user profile mapping during login
 
@@ -227,10 +384,10 @@ This would mainly be used to update relatively volatile information that you are
 
 In the map_rpx_data_each_login procedure, you will be writing to fields of the "self.attempted_record" object, pulling data from the @rpx_data object. For example:
 			
-	def map_rpx_data_each_login
-		# we'll always update photo_url
-		self.attempted_record.photo_url = @rpx_data['profile']['photo']
-	end
+  def map_rpx_data_each_login
+    # we'll always update photo_url
+    self.attempted_record.photo_url = @rpx_data['profile']['photo']
+  end
 
 {See the source for the sample user_session.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user_session.rb].
 
@@ -239,15 +396,12 @@ In the map_rpx_data_each_login procedure, you will be writing to fields of the "
 
 map_added_rpx_data maps additional fields from the RPX response into the user object during the "add RPX to existing account" process.
 
-By default, it only maps the rpx_identifier field. If you have other fields you want to map, you can provide your own implementation of the map_added_rpx_data method in the User model (NOT UserSession, unlike for map_rpx_data and map_rpx_data_each_login).
-
-NB: If you override this method, you will be responsible for also mapping the rpx_identifier.
+Override this in your user model to perform field mapping as may be desired. 
+Provide your own implementation of the map_added_rpx_data method in the User model (NOT UserSession, unlike for map_rpx_data and map_rpx_data_each_login).
 
 In the map_added_rpx_data procedure, you will be writing to fields of the "self" object, pulling data from the rpx_data parameter. For example:
 
 	def map_added_rpx_data( rpx_data )
-		self.rpx_identifier = rpx_data['profile']['identifier']
-
 		# map some additional fields, e.g. photo_url
 		self.photo_url = rpx_data['profile']['photo'] if photo_url.blank?
 	end
@@ -430,15 +584,15 @@ Each takes an options hash:
 
 For example, to insert a login link in a navigation bar is as simple as this:
 
-		&lt;div id="user_nav"&gt;
-			&lt;%= link_to "Home", root_path %&gt; |
-			&lt;% if current_user %&gt;
-				&lt;%= link_to "Profile", user_path(:current) %&gt; |
-				&lt;%= link_to "Sign out", signout_path %&gt;
-			&lt;% else %&gt;
-				&lt;%= rpx_popup( :link_text => "Register/Sign in with RPX..", :app_name => "rails-authlogic-rpx-sample", :return_url => user_sessions_url, :unobtrusive => false ) %>&gt;
-			&lt;% end %&gt;
-		&lt;/div&gt;
+  <div id="user_nav">
+    <%= link_to "Home", root_path %> |
+    <% if current_user %>
+    <%= link_to "Profile", user_path(:current) %> |
+    <%= link_to "Sign out", signout_path %>
+    <% else %>
+    <%= rpx_popup( :link_text => "Register/Sign in with RPX..", :app_name => "rails-authlogic-rpx-sample", :return_url => user_sessions_url, :unobtrusive => false ) %>>
+    <% end %>
+  </div>
 
 === 8. Allow users to "Add RPX" to existing accounts (optional)
 
@@ -448,18 +602,18 @@ However, if you support other authentication methods (e.g. by password), you pro
 
 The route may be called anything you like. Let's use "addrpxauth" for example. 
 
-	# This action has the special purpose of receiving an update of the RPX identity information
-	# for current user - to add RPX authentication to an existing non-RPX account.
-	# RPX only supports :post, so this cannot simply go to update method (:put)
-	def addrpxauth
-		@user = current_user
-		if @user.save
-			flash[:notice] = "Successfully added RPX authentication for this account."
-			render :action => 'show'
-		else
-			render :action => 'edit'
-		end
-	end
+  # This action has the special purpose of receiving an update of the RPX identity information
+  # for current user - to add RPX authentication to an existing non-RPX account.
+  # RPX only supports :post, so this cannot simply go to update method (:put)
+  def addrpxauth
+    @user = current_user
+    if @user.save
+      flash[:notice] = "Successfully added RPX authentication for this account."
+      render :action => 'show'
+    else
+      render :action => 'edit'
+    end
+  end
 
 {This is demonstrated in the sample users_controller.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/controllers/users_controller.rb].
 
@@ -469,10 +623,66 @@ You'll note this is almost identical to the "update". The main difference is tha
 
 To make an "Add RPX authentication for this account.." link, use rpx_popup as for normal RPX login, but set the return_url to the "addrpxauth" callback you have provided, and set the option :add_rpx to tru:
       
-  &lt;%= rpx_popup( :link_text =&gt; "Add RPX authentication for this account..", :app_name =&gt; RPX_APP_NAME, :return_url =&gt; addrpxauth_url, :add_rpx =&gt; true, :unobtrusive =&gt; false ) %&gt; 
+  <%= rpx_popup( :link_text => "Add RPX authentication for this account..", :app_name => RPX_APP_NAME, :return_url => addrpxauth_url, :add_rpx => true, :unobtrusive => false ) %> 
+
+
+=== 9. Customise Account Merge Behaviour (optional)
+
+Account merging is disabled by default. It is enabled by setting account_merge_enabled to true in the User model:
 
+  class User < ActiveRecord::Base
+  	acts_as_authentic do |c|
+  		c.account_merge_enabled true
+  	end
+  end	
+	
+ 
+Account merging is applicable if you have allowed users to add RPX to an existing accounts (see 8. Allow users to "Add RPX" to existing accounts). When merging is enabled, Authlogic_RPX will migrate the RPX login identifier(s) from other users who had previously claimed the identifiers now being used.
+
+For example, take the following scenario:
+* Joe registers and creates an account using RPX identifier A (say, a twitter account)
+* Joseph registers and creates an account using RPX identifier B (say, an OpenID account)
+* It so happens that Joe and Joseph are the same person...
+* Joseph signs in with RPX identifier B, and uses the "Add RPX" feature to attempt to add RPX identifier A to his account
+* At this point, if you have account_merge_enabled disabled (the default), it will fail since the id is already used by Joe
+* If you have account_merge_enabled enabled, Authlogic_RPX will transfer the RPX identifier A to Joseph's account
+  * If you are using account mapping = :none, RPX identifier A will just replace RPX identifier B for Joseph
+  * If you are using account mapping = :internal, RPX identifier A will be added to Joseph's account (he can now login with both A and B)
+* The default behaviour of account mapping will leave Joe's account in place (but with no way to login via RPX). Authlogic_RPX does not merge any other details (e.g. application data ownership)
+
+Authlogic_rpx provides two hooks for customising the account merge behaviour to handle things like migration of application objects and cleaning up old accounts:
+  
+* before_merge_rpx_data: called before the RPX identifiers are transfered. It provides a hook for application developers to perform data migration prior to the merging of user accounts. 
+* after_merge_rpx_data: called after the RPX identifiers are transfered. It provides a hook for application developers to perform account clean-up after (perhaps delete or disable to account merged from)
 
-=== 9. There is no 9
+
+The Authlogic_RPX sample application provides an example of migrating application objects and cleaning up obsolete accounts. From the user model:
+  
+  # before_merge_rpx_data provides a hook for application developers to perform data migration prior to the merging of user accounts.
+  # This method is called just before authlogic_rpx merges the user registration for 'from_user' into 'to_user'
+  # Authlogic_RPX is responsible for merging registration data.
+  #
+  # By default, it does not merge any other details (e.g. application data ownership)
+  #
+  def before_merge_rpx_data( from_user, to_user )
+  	RAILS_DEFAULT_LOGGER.info "in before_merge_rpx_data: migrate articles and comments from #{from_user.username} to #{to_user.username}"
+  	to_user.articles << from_user.articles
+  	to_user.comments << from_user.comments
+  end
+  
+  # after_merge_rpx_data provides a hook for application developers to perform account clean-up after authlogic_rpx has
+  # migrated registration details.
+  #
+  # By default, does nothing. It could, for example, be used to delete or disable the 'from_user' account
+  #
+  def after_merge_rpx_data( from_user, to_user )
+  	RAILS_DEFAULT_LOGGER.info "in after_merge_rpx_data: destroy #{from_user.inspect}"	
+  	from_user.destroy
+  end
+
+{See the sample user.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user.rb].
+
+=== Ready to try it?
 
 That's all there is. To see Authlogic_RPX in action, check out the demonstration Rails application:
 * <b>Live Demonstration Site:</b> [http://rails-authlogic-rpx-sample.heroku.com]
@@ -486,7 +696,6 @@ Authlogic_RPX is open source and hosted on {github}[http://github.com/tardate/au
 If you have issues or feedback, please log them in the {issues list on github}[http://github.com/tardate/authlogic_rpx/issues]
 
 Some of the improvements currently on the radar:
-* Still figuring out how to write some good automated tests
 * Implement/verify support for RPX "paid" service features of their "Plus" and "Pro" accounts (to date, only tested with free RPX "Basic" account)
 
 
@@ -514,6 +723,8 @@ Some design principles:
 * update gem version refs in README.rdoc
 * update CHANGELOG.rdoc
 
+Build and distribute (the gemcutter way):
+
   # update manifest file
   $ rake manifest
   # update gemspec
@@ -533,3 +744,4 @@ The idea of adding RPX support to authlogic is not new. Some early ideas were fo
 *	<b>http://github.com/gampleman/authlogic_rpx/</b> similar, but including an implementation of the RPX api
 
 authlogic_rpx was created by Paul Gallagher (tardate.com) and released under the MIT license.
+Big thanks for contributions from {John}[http://gitub.com/jjb] and {Damir}[http://gitub.com/sidonath]