Empact-authlogic_rpx 1.1.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (40) hide show
  1. data/.gitignore +1 -0
  2. data/CHANGELOG.rdoc +39 -0
  3. data/Empact-authlogic_rpx.gemspec +100 -0
  4. data/MIT-LICENSE +20 -0
  5. data/README.rdoc +747 -0
  6. data/Rakefile +47 -0
  7. data/VERSION +1 -0
  8. data/generators/add_authlogic_rpx_migration/USAGE +18 -0
  9. data/generators/add_authlogic_rpx_migration/add_authlogic_rpx_migration_generator.rb +44 -0
  10. data/generators/add_authlogic_rpx_migration/templates/migration_internal_mapping.rb +34 -0
  11. data/generators/add_authlogic_rpx_migration/templates/migration_no_mapping.rb +29 -0
  12. data/init.rb +1 -0
  13. data/lib/authlogic_rpx.rb +13 -0
  14. data/lib/authlogic_rpx/acts_as_authentic.rb +274 -0
  15. data/lib/authlogic_rpx/helper.rb +44 -0
  16. data/lib/authlogic_rpx/rpx_identifier.rb +5 -0
  17. data/lib/authlogic_rpx/session.rb +241 -0
  18. data/lib/authlogic_rpx/session/validation.rb +30 -0
  19. data/lib/authlogic_rpx/version.rb +51 -0
  20. data/rails/init.rb +1 -0
  21. data/test/fixtures/rpxresponses.yml +20 -0
  22. data/test/fixtures/users.yml +20 -0
  23. data/test/integration/basic_authentication_and_registration_test.rb +73 -0
  24. data/test/integration/internal_mapping/basic_authentication_and_registration_test.rb +3 -0
  25. data/test/integration/internal_mapping/settings_test.rb +10 -0
  26. data/test/integration/no_mapping/basic_authentication_and_registration_test.rb +3 -0
  27. data/test/integration/no_mapping/settings_test.rb +10 -0
  28. data/test/libs/ext_test_unit.rb +30 -0
  29. data/test/libs/mock_rpx_now.rb +34 -0
  30. data/test/libs/rails_trickery.rb +41 -0
  31. data/test/libs/rpxresponse.rb +3 -0
  32. data/test/libs/user.rb +3 -0
  33. data/test/libs/user_session.rb +3 -0
  34. data/test/test_helper.rb +85 -0
  35. data/test/test_internal_mapping_helper.rb +93 -0
  36. data/test/unit/acts_as_authentic_settings_test.rb +42 -0
  37. data/test/unit/session_settings_test.rb +38 -0
  38. data/test/unit/session_validation_test.rb +16 -0
  39. data/test/unit/verify_rpx_mock_test.rb +29 -0
  40. metadata +143 -0
data/.gitignore ADDED
@@ -0,0 +1 @@
1
+ pkg/
data/CHANGELOG.rdoc ADDED
@@ -0,0 +1,39 @@
1
+ == 1.1.1 released 2010-01-17
2
+
3
+ * updated gem support to rpx_now 0.6.12 (includes url encoding fix)
4
+
5
+ == 1.1.0 released 2010-01-05
6
+
7
+ * added identity mapping and merging support [GH#10,GH#13]
8
+ * new configuration parameters: account_mapping_mode; account_merge_enabled.
9
+ * new callbacks: before_merge_rpx_data; after_merge_rpx_data.
10
+ * updated gem support to authlogic 2.1.3 and rpx_now 0.6.11
11
+ * support all rpx_now options in popup/embed code [GH#6]
12
+ * automated tests are now working [GH#7]
13
+ * documentation updates
14
+
15
+ == 1.0.4 released 2009-10-10
16
+
17
+ * 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)
18
+ * now supporting obtrusive (javascript pop-over) and unobtrusive (link) RPX pop-up sign-in forms. See rpx_popup method. (github issue #4)
19
+ * updated support for rpx_now gem version 0.6.6
20
+ * documentation updates
21
+
22
+ == 1.0.3 released 2009-10-07
23
+
24
+ * added general error handler for session validation to give clean 'failure' when underlying errors encountered (e.g. user model database constraint violation)
25
+ * updated documentation
26
+
27
+ == 1.0.2 released 2009-09-27
28
+
29
+ * Fixed issue with rpx_popup that was causing an error on some webkit-based browsers (incl chrome)
30
+
31
+ == 1.0.1 released 2009-09-26
32
+
33
+ * Initial public release
34
+ * RPX profile mappings switched to use indirect Authlogic field naming
35
+ * Documentation updated
36
+
37
+ == 1.0.0 released 2009-09-25
38
+
39
+ * Initial release
@@ -0,0 +1,100 @@
1
+ # Generated by jeweler
2
+ # DO NOT EDIT THIS FILE DIRECTLY
3
+ # Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
4
+ # -*- encoding: utf-8 -*-
5
+
6
+ Gem::Specification.new do |s|
7
+ s.name = %q{Empact-authlogic_rpx}
8
+ s.version = "1.1.2"
9
+
10
+ s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
11
+ s.authors = ["Paul Gallagher / tardate"]
12
+ s.date = %q{2010-02-25}
13
+ s.description = %q{Authlogic extension/plugin that provides RPX (rpxnow.com) authentication support}
14
+ s.email = %q{gallagher.paul@gmail.com}
15
+ s.extra_rdoc_files = [
16
+ "README.rdoc"
17
+ ]
18
+ s.files = [
19
+ ".gitignore",
20
+ "CHANGELOG.rdoc",
21
+ "Empact-authlogic_rpx.gemspec",
22
+ "MIT-LICENSE",
23
+ "README.rdoc",
24
+ "Rakefile",
25
+ "VERSION",
26
+ "generators/add_authlogic_rpx_migration/USAGE",
27
+ "generators/add_authlogic_rpx_migration/add_authlogic_rpx_migration_generator.rb",
28
+ "generators/add_authlogic_rpx_migration/templates/migration_internal_mapping.rb",
29
+ "generators/add_authlogic_rpx_migration/templates/migration_no_mapping.rb",
30
+ "init.rb",
31
+ "lib/authlogic_rpx.rb",
32
+ "lib/authlogic_rpx/acts_as_authentic.rb",
33
+ "lib/authlogic_rpx/helper.rb",
34
+ "lib/authlogic_rpx/rpx_identifier.rb",
35
+ "lib/authlogic_rpx/session.rb",
36
+ "lib/authlogic_rpx/session/validation.rb",
37
+ "lib/authlogic_rpx/version.rb",
38
+ "rails/init.rb",
39
+ "test/fixtures/rpxresponses.yml",
40
+ "test/fixtures/users.yml",
41
+ "test/integration/basic_authentication_and_registration_test.rb",
42
+ "test/integration/internal_mapping/basic_authentication_and_registration_test.rb",
43
+ "test/integration/internal_mapping/settings_test.rb",
44
+ "test/integration/no_mapping/basic_authentication_and_registration_test.rb",
45
+ "test/integration/no_mapping/settings_test.rb",
46
+ "test/libs/ext_test_unit.rb",
47
+ "test/libs/mock_rpx_now.rb",
48
+ "test/libs/rails_trickery.rb",
49
+ "test/libs/rpxresponse.rb",
50
+ "test/libs/user.rb",
51
+ "test/libs/user_session.rb",
52
+ "test/test_helper.rb",
53
+ "test/test_internal_mapping_helper.rb",
54
+ "test/unit/acts_as_authentic_settings_test.rb",
55
+ "test/unit/session_settings_test.rb",
56
+ "test/unit/session_validation_test.rb",
57
+ "test/unit/verify_rpx_mock_test.rb"
58
+ ]
59
+ s.homepage = %q{http://github.com/tardate/authlogic_rpx}
60
+ s.rdoc_options = ["--charset=UTF-8"]
61
+ s.require_paths = ["lib"]
62
+ s.rubygems_version = %q{1.3.6}
63
+ s.summary = %q{Authlogic plug-in for RPX support}
64
+ s.test_files = [
65
+ "test/integration/basic_authentication_and_registration_test.rb",
66
+ "test/integration/internal_mapping/basic_authentication_and_registration_test.rb",
67
+ "test/integration/internal_mapping/settings_test.rb",
68
+ "test/integration/no_mapping/basic_authentication_and_registration_test.rb",
69
+ "test/integration/no_mapping/settings_test.rb",
70
+ "test/libs/ext_test_unit.rb",
71
+ "test/libs/mock_rpx_now.rb",
72
+ "test/libs/rails_trickery.rb",
73
+ "test/libs/rpxresponse.rb",
74
+ "test/libs/user.rb",
75
+ "test/libs/user_session.rb",
76
+ "test/test_helper.rb",
77
+ "test/test_internal_mapping_helper.rb",
78
+ "test/unit/acts_as_authentic_settings_test.rb",
79
+ "test/unit/session_settings_test.rb",
80
+ "test/unit/session_validation_test.rb",
81
+ "test/unit/verify_rpx_mock_test.rb"
82
+ ]
83
+
84
+ if s.respond_to? :specification_version then
85
+ current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
86
+ s.specification_version = 3
87
+
88
+ if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
89
+ s.add_runtime_dependency(%q<authlogic>, [">= 2.1.3"])
90
+ s.add_runtime_dependency(%q<rpx_now>, [">= 0.6.12"])
91
+ else
92
+ s.add_dependency(%q<authlogic>, [">= 2.1.3"])
93
+ s.add_dependency(%q<rpx_now>, [">= 0.6.12"])
94
+ end
95
+ else
96
+ s.add_dependency(%q<authlogic>, [">= 2.1.3"])
97
+ s.add_dependency(%q<rpx_now>, [">= 0.6.12"])
98
+ end
99
+ end
100
+
data/MIT-LICENSE ADDED
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2009 Paul Gallagher (tardate.com)
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.rdoc ADDED
@@ -0,0 +1,747 @@
1
+ = Authlogic_RPX
2
+
3
+ == Purpose
4
+
5
+ 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.
6
+
7
+ Key features and capabilities:
8
+ * Auto-registration by default following RPX authentication (can be disabled if required)
9
+ * Can allow users to enable RPX authentication for their existing password-enabled accounts
10
+ * View helpers to assist with inserting login fragments in pages
11
+ * Can co-exist with standard password authentication
12
+ * Supports identity mapping and merging (allowing users to have multiple logins associated with one member record on your site)
13
+
14
+
15
+ == Authlogic_RPX References
16
+
17
+ * <b>Authlogic_RPX gem repo:</b> [http://github.com/tardate/authlogic_rpx]
18
+ * <b>Authlogic_RPX issues and feedback:</b> [http://github.com/tardate/authlogic_rpx/issues]
19
+
20
+ The demonstration Rails application is where you can see Authlogic_RPX in action:
21
+
22
+ * <b>Live Demonstration Site:</b> [http://rails-authlogic-rpx-sample.heroku.com]
23
+ * <b>Demonstration site source repository:</b> [http://github.com/tardate/rails-authlogic-rpx-sample]
24
+
25
+ == Authlogic and RPX References
26
+
27
+ * <b>Authlogic documentation:</b> [http://rdoc.info/projects/binarylogic/authlogic]
28
+ * <b>Authlogic repo:</b> [http://github.com/binarylogic/authlogic]
29
+ * <b>RPX documentation:</b> [https://rpxnow.com/docs]
30
+ * <b>RPX_now gem repo:</b> [http://github.com/grosser/rpx_now]
31
+
32
+
33
+ == Installing Authlogic_RPX gem
34
+
35
+ Three gems are required: authlogic, rpx_now, and authlogic_rpx. Install these as appropriate to your environment and preferences.
36
+
37
+ Currently tested versions:
38
+ * authlogic 2.1.3,2.1.2,2.1.1
39
+ * rpx_now 0.6.12 (0.6.11,0.6.6 support is deprecated)
40
+ * authlogic_rpx 1.1.1
41
+
42
+
43
+ === 1. Direct gem installation
44
+
45
+ sudo gem install authlogic
46
+ sudo gem install rpx_now --source http://gemcutter.org
47
+ sudo gem install authlogic_rpx --source http://gemcutter.org
48
+
49
+
50
+ === 2. Using Rails config.gems
51
+
52
+ Include in config/environment.rb:
53
+
54
+ config.gem 'authlogic', :version => '>= 2.1.3'
55
+ config.gem 'rpx_now', :version => '>= 0.6.12', :source => 'http://gemcutter.org'
56
+ config.gem 'authlogic_rpx', :version => '>= 1.1.1', :source => 'http://gemcutter.org'
57
+
58
+ Then to install, run from the command line:
59
+
60
+ sudo rake gems:install
61
+
62
+
63
+ === 3. Using .gems file (e.g for heroku.com deployments)
64
+
65
+ Include in RAILS_ROOT/.gems:
66
+
67
+ authlogic --version '>= 2.1.3'
68
+ rpx_now --version '>= 0.6.12' --source gemcutter.org
69
+ authlogic_rpx --version '>= 1.1.1' --source gemcutter.org
70
+
71
+
72
+ == About Authlogic_RPX
73
+
74
+ 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.
75
+
76
+ 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.
77
+
78
+ 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).
79
+
80
+ 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'.
81
+
82
+ 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.
83
+
84
+ === Chosing Your Mapping Mode
85
+
86
+ When you configure Authlogic_RPX, you will need to decide which mapping mode to use.
87
+
88
+ The options are:
89
+ * :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
90
+ * :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.
91
+ * :rpxnow - currently not implemented; reserved for future use
92
+
93
+
94
+ ==== Upgrading from Authlogic_RPX 1.0.4 or earlier
95
+
96
+ In Authlogic_RPX v1.0.4 and earlier, the rpx_identifier was stored in the user model, and identity mapping was not supported.
97
+
98
+ If you are upgrading to 1.1.0 or later and wish to start using internal mapping:
99
+ * Use the add_authlogic_rpx_migration generator to create the migration to support the new RPXIdentifiers model
100
+ * It is NOT necessary to migrate the rpx_identifiers.
101
+ * 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.
102
+ * You may wish to explicitly set account_mapping_mode to :internal in the User model (it saves a few cycles over the default :auto).
103
+
104
+ e.g.
105
+
106
+ class User < ActiveRecord::Base
107
+ acts_as_authentic do |c|
108
+ c.account_mapping_mode :internal
109
+ end
110
+ end
111
+
112
+ 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):
113
+ * You will already have the rpx_identifier in your user model. DO NOT create any new migrations.
114
+ * Just upgrade the gem and all should continue to work as before
115
+ * You may wish to explicitly set account_mapping_mode to :none in the User model (it saves a few cycles over the default :auto).
116
+
117
+ e.g.
118
+
119
+ class User < ActiveRecord::Base
120
+ acts_as_authentic do |c|
121
+ c.account_mapping_mode :none
122
+ end
123
+ end
124
+
125
+ == The Step-by-Step Guide to Using Authlogic_RPX
126
+
127
+ <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>
128
+
129
+ The main steps for enabling Authlogic_RPX:
130
+ * 1. Enable RPX for your user model
131
+ * 2. Add RPX configuration for the Authlogic session model
132
+ * 3. Add custom user profile mapping (optional)
133
+ * 4. Add application controller helpers: current_user, current_user_session
134
+ * 5. Setup the Authlogic session controller
135
+ * 6. Setup the Authlogic user controller
136
+ * 7. Use view helpers to provide login links
137
+ * 8. Allow users to "Add RPX" to existing accounts (optional)
138
+ * 9. Customise Account Merge Behaviour (optional)
139
+
140
+
141
+ === 1. Enable RPX for your user model
142
+
143
+ The user model will have a has_many relationship with a new model, called RPXIdentifier.
144
+ A generator is provider to create the necessary migration:
145
+
146
+ ruby script/generate add_authlogic_rpx_migration [mapping:mapping_mode] [user_model:model_name]
147
+
148
+ The generator takes two optional parameters: mapping and user_model.
149
+
150
+ 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:
151
+ * none (disables authlogic_rpx identity mapping. This is the same behaviour as in authlogic_rpx version 1.0.4 and earlier)
152
+ * internal (enables authlogic_rpx internal identity mapping. This behaviour was introduced in version 1.1.0)
153
+
154
+ 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:
155
+
156
+ ruby script/generate add_authlogic_rpx_migration mapping:none user_model:member
157
+
158
+ You may need to customise the migration file to remove database constraints on other fields if they will be unused in the RPX case
159
+ (e.g. crypted_password and password_salt to make password authentication optional).
160
+
161
+ If you are using auto-registration, you must also remove any database constraints for fields that will be automatically mapped
162
+ (see notes in "3. Add custom user profile mapping during auto-registration")
163
+
164
+ ==== Sample Migration Generated Script (using internal mapping)
165
+
166
+ 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':
167
+
168
+ ruby script/generate add_authlogic_rpx_migration mapping:internal user_model:user
169
+
170
+ The migration script will appear like this:
171
+
172
+ class AddAuthlogicRpxMigration < ActiveRecord::Migration
173
+ def self.up
174
+ create_table :rpx_identifiers do |t|
175
+ t.string :identifier, :null => false
176
+ t.string :provider_name
177
+ t.integer :user_id, :null => false
178
+ t.timestamps
179
+ end
180
+ add_index :rpx_identifiers, :identifier, :unique => true, :null => false
181
+ add_index :rpx_identifiers, :user_id, :unique => false, :null => false
182
+
183
+ # == Customisation may be required here ==
184
+ # You may need to remove database constraints on other fields if they will be unused in the RPX case
185
+ # (e.g. crypted_password and password_salt to make password authentication optional).
186
+ # If you are using auto-registration, you must also remove any database constraints for fields that will be automatically mapped
187
+ # e.g.:
188
+ #change_column :users, :crypted_password, :string, :default => nil, :null => true
189
+ #change_column :users, :password_salt, :string, :default => nil, :null => true
190
+
191
+ end
192
+
193
+ def self.down
194
+ drop_table :rpx_identifiers
195
+
196
+ # == Customisation may be required here ==
197
+ # Restore user model database constraints as appropriate
198
+ # e.g.:
199
+ #[:crypted_password, :password_salt].each do |field|
200
+ # User.all(:conditions => "#{field} is NULL").each { |user| user.update_attribute(field, "") if user.send(field).nil? }
201
+ # change_column :users, field, :string, :default => "", :null => false
202
+ #end
203
+
204
+ end
205
+ end
206
+
207
+ {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].
208
+
209
+ ==== Sample Migration Generated Script (using no mapping)
210
+
211
+ 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':
212
+
213
+ ruby script/generate add_authlogic_rpx_migration mapping:none user_model:member
214
+
215
+ The migration script will appear like this:
216
+
217
+ class AddAuthlogicRpxMigration < ActiveRecord::Migration
218
+
219
+ def self.up
220
+ add_column :members, :rpx_identifier, :string
221
+ add_index :members, :rpx_identifier
222
+
223
+ # == Customisation may be required here ==
224
+ # You may need to remove database constraints on other fields if they will be unused in the RPX case
225
+ # (e.g. crypted_password and password_salt to make password authentication optional).
226
+ # If you are using auto-registration, you must also remove any database constraints for fields that will be automatically mapped
227
+
228
+ # e.g.:
229
+ #change_column :members, :crypted_password, :string, :default => nil, :null => true
230
+ #change_column :members, :password_salt, :string, :default => nil, :null => true
231
+
232
+ end
233
+
234
+ def self.down
235
+ remove_column :members, :rpx_identifier
236
+
237
+ # == Customisation may be required here ==
238
+ # Restore user model database constraints as appropriate
239
+ # e.g.:
240
+ #[:crypted_password, :password_salt].each do |field|
241
+ # Member.all(:conditions => "#{field} is NULL").each { |user| user.update_attribute(field, "") if user.send(field).nil? }
242
+ # change_column :members, field, :string, :default => "", :null => false
243
+ #end
244
+
245
+ end
246
+ end
247
+
248
+ ==== Configuring the User model
249
+
250
+ The user model then needs to be tagged with "acts_as_authentic". This is the minimal configuration:
251
+
252
+ class User < ActiveRecord::Base
253
+ acts_as_authentic
254
+ end
255
+
256
+ Two RPX-specific user configuration options are available.
257
+ * account_merge_enabled: true/false. Enables/disables user auto-registration (disabled by default)
258
+ * account_mapping_mode: :auto/:none/:internal. Sets the Authlogic_RPX identity mapping mode (:auto by default)
259
+
260
+ The account_mapping_mode options are defined as follows:
261
+ * :auto - will select the correct mapping mode based on the table structures you have provisioned in the application
262
+ * :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
263
+ * :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.
264
+ * :rpxnow - currently not implemented; reserved for future use.
265
+
266
+ For example, the following shows how to set standard Authlogic configurations (validations_scope), enables RPX account merging, and specifies :internal account mapping:
267
+
268
+ class User < ActiveRecord::Base
269
+ acts_as_authentic do |c|
270
+ c.validations_scope = :company_id # for available Authlogic options see documentation in the various Config modules of Authlogic::ActsAsAuthentic
271
+
272
+ # enable Authlogic_RPX account merging (false by default, if this statement is not present)
273
+ c.account_merge_enabled true
274
+
275
+ # set Authlogic_RPX account mapping mode
276
+ c.account_mapping_mode :internal
277
+
278
+ end # block optional
279
+
280
+ end
281
+
282
+ {See the source for the sample user.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user.rb].
283
+
284
+ NB: The RPXIdentifier model is included in the authlogic_rpx gem and does not need to be added to your project.
285
+
286
+ === 2. Add RPX configuration for the Authlogic session model
287
+
288
+ Authlogic provides a helper to create the session model:
289
+
290
+ script/generate session user_session
291
+
292
+ The minimum configuration required is to add your RPX_API_KEY:
293
+
294
+ class UserSession < Authlogic::Session::Base
295
+ rpx_key RPX_API_KEY
296
+ end
297
+
298
+ Get an API key by registering your application at {RPX}[http://rpxnow.com/]. A free "Basic" account is available, in addition to paid enhanced versions. All work with Authlogic_RPX.
299
+
300
+ You probably don't want to put your API key in directly. A recommended approach is to set the key as an environment variable, and then set it as a constant in config/environment.rb:
301
+
302
+ RPX_API_KEY = ENV['RPX_API_KEY']
303
+
304
+ Two additional RPX-specific session configuration options are available.
305
+ * auto_register: enable/disable user auto-registration (enabled by default)
306
+ * rpx_extended_info: enable/disable extended profile information in the RPX authentication (disabled by default)
307
+
308
+ For example, to disable auto-registration and enable extended info:
309
+
310
+ class UserSession < Authlogic::Session::Base
311
+ rpx_key RPX_API_KEY
312
+ auto_register false
313
+ rpx_extended_info
314
+ end
315
+
316
+ {See the source for the sample user_session.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user_session.rb].
317
+
318
+ === 3. Add custom user profile mapping (optional)
319
+
320
+ Authlogic_rpx provides three hooks for mapping information from the RPX profile into your application's user model:
321
+
322
+ * map_rpx_data: user profile mapping during auto-registration
323
+ * map_rpx_data_each_login: user profile mapping during login
324
+ * map_added_rpx_data: user profile mapping when adding RPX to an existing account
325
+
326
+ See https://rpxnow.com/docs#profile_data for the definition of available attributes in the RPX profile.
327
+
328
+ ==== 3a. map_rpx_data: user profile mapping during auto-registration
329
+
330
+ 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.
331
+
332
+ If you have other fields you want to map, you can provide your own implementation of the map_rpx_data method in the UserSession model. In that method, you will be updating the "self.attempted_record" object, with information from the "@rpx_data" object. See the {RPX documentation}[https://rpxnow.com/docs#profile_data] to find out about the set of information that is available.
333
+
334
+ class UserSession < Authlogic::Session::Base
335
+ rpx_key RPX_API_KEY
336
+ rpx_extended_info
337
+
338
+ private
339
+
340
+ # map_rpx_data maps additional fields from the RPX response into the user object
341
+ # override this in your session controller to change the field mapping
342
+ # see https://rpxnow.com/docs#profile_data for the definition of available attributes
343
+ #
344
+ def map_rpx_data
345
+ # map core profile data using authlogic indirect column names
346
+ self.attempted_record.send("#{klass.login_field}=", @rpx_data['profile']['preferredUsername'] ) if attempted_record.send(klass.login_field).blank?
347
+ self.attempted_record.send("#{klass.email_field}=", @rpx_data['profile']['email'] ) if attempted_record.send(klass.email_field).blank?
348
+
349
+ # map some other columns explicitly
350
+ self.attempted_record.fullname = @rpx_data['profile']['displayName'] if attempted_record.fullname.blank?
351
+
352
+ if rpx_extended_info?
353
+ # map some extended attributes
354
+ end
355
+ end
356
+
357
+ end
358
+
359
+
360
+ WARNING: if you are using auto-registration, any fields you map should NOT have constraints enforced at the database level.
361
+ Authlogic_rpx will optimistically attempt to save the user record during registration, and violating a database constraint will cause the authentication/registration to fail.
362
+
363
+ You can/should enforce any required validations at the model level e.g.
364
+
365
+ validates_uniqueness_of :username, :case_sensitive => false
366
+
367
+ This will allow the auto-registration to proceed, and the user can be given a chance to rectify the validation errors on your user profile page.
368
+
369
+ If it is not acceptable in your application to have user records created with potential validation errors in auto-populated fields, you will need to override map_rpx_data and implement whatever special handling makes sense in your case. For example:
370
+
371
+ * directly check for uniqueness and other validation requirements
372
+ * automatically "uniquify" certain fields like username
373
+ * save conflicting profile information to "pending user review" columns or a seperate table
374
+
375
+ {See the source for the sample user_session.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user_session.rb].
376
+
377
+ ==== 3b. map_rpx_data_each_login: user profile mapping during login
378
+
379
+ map_rpx_data_each_login provides a hook to allow you to map RPX profile information every time the user logs in.
380
+
381
+ By default, nothing is mapped. If you have other fields you want to map, you can provide your own implementation of the map_rpx_data_each_login method in the UserSession model.
382
+
383
+ This would mainly be used to update relatively volatile information that you are maintaining in the user model (such as profile image url)
384
+
385
+ 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:
386
+
387
+ def map_rpx_data_each_login
388
+ # we'll always update photo_url
389
+ self.attempted_record.photo_url = @rpx_data['profile']['photo']
390
+ end
391
+
392
+ {See the source for the sample user_session.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user_session.rb].
393
+
394
+
395
+ ==== 3c. map_added_rpx_data: user profile mapping when adding RPX to an existing account
396
+
397
+ map_added_rpx_data maps additional fields from the RPX response into the user object during the "add RPX to existing account" process.
398
+
399
+ Override this in your user model to perform field mapping as may be desired.
400
+ 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).
401
+
402
+ 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:
403
+
404
+ def map_added_rpx_data( rpx_data )
405
+ # map some additional fields, e.g. photo_url
406
+ self.photo_url = rpx_data['profile']['photo'] if photo_url.blank?
407
+ end
408
+
409
+ {See the source for the sample user.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user.rb].
410
+
411
+
412
+ === 4. Add application controller helpers: current_user, current_user_session
413
+
414
+ We'll add current_user and current_user_session helpers. These can then be used in controllers and views to get a handle on the "current" logged in user.
415
+
416
+ class ApplicationController < ActionController::Base
417
+ helper :all # include all helpers, all the time
418
+ protect_from_forgery # See ActionController::RequestForgeryProtection for details
419
+
420
+ # Scrub sensitive parameters from your log
421
+ filter_parameter_logging :password, :password_confirmation
422
+
423
+ helper_method :current_user, :current_user_session
424
+
425
+ private
426
+
427
+ def current_user_session
428
+ return @current_user_session if defined?(@current_user_session)
429
+ @current_user_session = UserSession.find
430
+ end
431
+
432
+ def current_user
433
+ return @current_user if defined?(@current_user)
434
+ @current_user = current_user_session && current_user_session.record
435
+ end
436
+ end
437
+
438
+ {See the source for the sample user_session_controller.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/controllers/application_controller.rb].
439
+
440
+
441
+ === 5. Setup the Authlogic session controller
442
+
443
+ If you don't already have a user session controller, create one. There are four actions of significance for authlogic_rpx:
444
+
445
+ $ script/generate controller user_sessions index new create destroy
446
+
447
+ {See the source for the sample user_session_controller.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/controllers/user_sessions_controller.rb].
448
+
449
+ In config/routes.rb we can define the standard routes for this controller and two named routes for the main login/out (or singin/out if you prefer that terminology):
450
+
451
+ map.signin "signin", :controller => "user_sessions", :action => "new"
452
+ map.signout "signout", :controller => "user_sessions", :action => "destroy"
453
+ map.resources :user_sessions
454
+
455
+ ==== index
456
+ This is where RPX will return to if the user cancelled the login process, so it needs to be handled. You probably just want to redirect the user to an appropriate alternative:
457
+
458
+ def index
459
+ redirect_to current_user ? root_url : new_user_session_url
460
+ end
461
+
462
+ ==== new
463
+ Typically used to render a login form
464
+
465
+ def new
466
+ @user_session = UserSession.new
467
+ end
468
+
469
+ ==== create
470
+ This is where the magic happens for authentication. Authlogic hides all the underlying wiring, and you just need to "save" the session!
471
+
472
+ Authlogic_rpx provides two additional methods that you might want to use to tailor you application behaviour:
473
+ * new_registration? - if a new registration, e.g. force them to go via a registration follow-up page
474
+ * registration_complete? - if registration details not complete, e.g. bounce the user over the profile editing page
475
+
476
+ def create
477
+ @user_session = UserSession.new(params[:user_session])
478
+ if @user_session.save
479
+ if @user_session.new_registration?
480
+ flash[:notice] = "Welcome! As a new user, please review your registration details before continuing.."
481
+ redirect_to edit_user_path( :current )
482
+ else
483
+ if @user_session.registration_complete?
484
+ flash[:notice] = "Successfully signed in."
485
+ redirect_back_or_default articles_path
486
+ else
487
+ flash[:notice] = "Welcome back! Please complete required registration details before continuing.."
488
+ redirect_to edit_user_path( :current )
489
+ end
490
+ end
491
+ else
492
+ flash[:error] = "Failed to login or register."
493
+ redirect_to new_user_session_path
494
+ end
495
+ end
496
+
497
+ ==== destroy
498
+ The logout action..
499
+
500
+ def destroy
501
+ @user_session = current_user_session
502
+ @user_session.destroy if @user_session
503
+ flash[:notice] = "Successfully signed out."
504
+ redirect_to articles_path
505
+ end
506
+
507
+
508
+ === 6. Setup the Authlogic user controller
509
+
510
+ The users controller handles the actual user creation and editing actions. In it's standard form, it looks like any other controller with an underlying ActiveRecord model.
511
+
512
+ There are five basic actions to consider. If you don't already have a controller, create it:
513
+
514
+ $ script/generate controller users new create edit show update
515
+
516
+ {See the source for the sample users_controller.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/controllers/users_controller.rb].
517
+
518
+ The users controller just needs standard routes defined in config/routes.rb:
519
+
520
+ map.resources :users
521
+
522
+ ==== new
523
+ Stock standard form for a user to register on the site. Only required if you will allow users to register without using RPX auto-registration (using standard password authentication).
524
+
525
+ def new
526
+ @user = User.new
527
+ end
528
+
529
+ ==== create
530
+ As for new, stock standard and only required if you will allow users to register without using RPX auto-registration.
531
+
532
+ def create
533
+ @user = User.new(params[:user])
534
+ if @user.save
535
+ flash[:notice] = "Successfully registered user."
536
+ redirect_to articles_path
537
+ else
538
+ render :action => 'new'
539
+ end
540
+ end
541
+
542
+ ==== show
543
+ Display's the user's profile. Uses the current_user helper that we'll include in the application controller.
544
+
545
+ def show
546
+ @user = current_user
547
+ end
548
+
549
+ ==== edit
550
+ Allows the user to edit their profile. Calling valid? will ensure any validation errors are highlighted. This can be relevant with RPX since auto-registration may not include all the profile data you want to make "mandatory" for normal users.
551
+
552
+ def edit
553
+ @user = current_user
554
+ @user.valid?
555
+ end
556
+
557
+ ==== update
558
+ Handles the submission of the edit form. Again, uses the current_user helper that we'll include in the application controller.
559
+
560
+ def update
561
+ @user = current_user
562
+ @user.attributes = params[:user]
563
+ if @user.save
564
+ flash[:notice] = "Successfully updated user."
565
+ redirect_back_or_default articles_path
566
+ else
567
+ render :action => 'edit'
568
+ end
569
+ end
570
+
571
+
572
+ === 7. Use view helpers to provide login links
573
+
574
+ So how to put a "login" link on your page? Two helper methods are provided:
575
+ * <b>rpx_popup</b> helper to insert a link to pop-up RPX login
576
+ * <b>rpx_embed</b> helper to insert an embedded iframe RPX login form
577
+
578
+ Each takes an options hash:
579
+ * <tt>link_text:</tt> text to use in the link (only used by rpx_popup)
580
+ * <tt>app_name:</tt> name of the application you set when registering your service at rpxnow.com (will be prepended to RPX domain and used in RPX dialogues)
581
+ * <tt>return_url:</tt> url for the RPX callback (e.g. user_sessions_url)
582
+ * <tt>add_rpx:</tt> Optional. If true, requests RPX callback to add to current session. Else runs normal authentication process (default). See "7. Allow users to "Add RPX" to existing accounts"
583
+ * <tt>unobtrusive:</tt> true/false; sets javascript style for link. unobtrusive=true links directly to rpxnow site, whereas unobtrusive=false does a javascript pop-over. Default: true (only used by rpx_popup)
584
+
585
+ For example, to insert a login link in a navigation bar is as simple as this:
586
+
587
+ <div id="user_nav">
588
+ <%= link_to "Home", root_path %> |
589
+ <% if current_user %>
590
+ <%= link_to "Profile", user_path(:current) %> |
591
+ <%= link_to "Sign out", signout_path %>
592
+ <% else %>
593
+ <%= rpx_popup( :link_text => "Register/Sign in with RPX..", :app_name => "rails-authlogic-rpx-sample", :return_url => user_sessions_url, :unobtrusive => false ) %>>
594
+ <% end %>
595
+ </div>
596
+
597
+ === 8. Allow users to "Add RPX" to existing accounts (optional)
598
+
599
+ If you got this far and have a working application, you are ready to go, especially if you only plan to support RPX authentication.
600
+
601
+ However, if you support other authentication methods (e.g. by password), you probably want the ability to let user's add RPX to an existing account. This is not possible by default, however adding it is simply a matter of providing another method on your user controller.
602
+
603
+ The route may be called anything you like. Let's use "addrpxauth" for example.
604
+
605
+ # This action has the special purpose of receiving an update of the RPX identity information
606
+ # for current user - to add RPX authentication to an existing non-RPX account.
607
+ # RPX only supports :post, so this cannot simply go to update method (:put)
608
+ def addrpxauth
609
+ @user = current_user
610
+ if @user.save
611
+ flash[:notice] = "Successfully added RPX authentication for this account."
612
+ render :action => 'show'
613
+ else
614
+ render :action => 'edit'
615
+ end
616
+ end
617
+
618
+ {This is demonstrated in the sample users_controller.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/controllers/users_controller.rb].
619
+
620
+ You'll note this is almost identical to the "update". The main difference is that it needs to be enabled for :post by RPX. In config/routes.rb:
621
+
622
+ map.addrpxauth "addrpxauth", :controller => "users", :action => "addrpxauth", :method => :post
623
+
624
+ 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:
625
+
626
+ <%= rpx_popup( :link_text => "Add RPX authentication for this account..", :app_name => RPX_APP_NAME, :return_url => addrpxauth_url, :add_rpx => true, :unobtrusive => false ) %>
627
+
628
+
629
+ === 9. Customise Account Merge Behaviour (optional)
630
+
631
+ Account merging is disabled by default. It is enabled by setting account_merge_enabled to true in the User model:
632
+
633
+ class User < ActiveRecord::Base
634
+ acts_as_authentic do |c|
635
+ c.account_merge_enabled true
636
+ end
637
+ end
638
+
639
+
640
+ 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.
641
+
642
+ For example, take the following scenario:
643
+ * Joe registers and creates an account using RPX identifier A (say, a twitter account)
644
+ * Joseph registers and creates an account using RPX identifier B (say, an OpenID account)
645
+ * It so happens that Joe and Joseph are the same person...
646
+ * Joseph signs in with RPX identifier B, and uses the "Add RPX" feature to attempt to add RPX identifier A to his account
647
+ * At this point, if you have account_merge_enabled disabled (the default), it will fail since the id is already used by Joe
648
+ * If you have account_merge_enabled enabled, Authlogic_RPX will transfer the RPX identifier A to Joseph's account
649
+ * If you are using account mapping = :none, RPX identifier A will just replace RPX identifier B for Joseph
650
+ * 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)
651
+ * 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)
652
+
653
+ Authlogic_rpx provides two hooks for customising the account merge behaviour to handle things like migration of application objects and cleaning up old accounts:
654
+
655
+ * 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.
656
+ * 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)
657
+
658
+
659
+ The Authlogic_RPX sample application provides an example of migrating application objects and cleaning up obsolete accounts. From the user model:
660
+
661
+ # before_merge_rpx_data provides a hook for application developers to perform data migration prior to the merging of user accounts.
662
+ # This method is called just before authlogic_rpx merges the user registration for 'from_user' into 'to_user'
663
+ # Authlogic_RPX is responsible for merging registration data.
664
+ #
665
+ # By default, it does not merge any other details (e.g. application data ownership)
666
+ #
667
+ def before_merge_rpx_data( from_user, to_user )
668
+ RAILS_DEFAULT_LOGGER.info "in before_merge_rpx_data: migrate articles and comments from #{from_user.username} to #{to_user.username}"
669
+ to_user.articles << from_user.articles
670
+ to_user.comments << from_user.comments
671
+ end
672
+
673
+ # after_merge_rpx_data provides a hook for application developers to perform account clean-up after authlogic_rpx has
674
+ # migrated registration details.
675
+ #
676
+ # By default, does nothing. It could, for example, be used to delete or disable the 'from_user' account
677
+ #
678
+ def after_merge_rpx_data( from_user, to_user )
679
+ RAILS_DEFAULT_LOGGER.info "in after_merge_rpx_data: destroy #{from_user.inspect}"
680
+ from_user.destroy
681
+ end
682
+
683
+ {See the sample user.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user.rb].
684
+
685
+ === Ready to try it?
686
+
687
+ That's all there is. To see Authlogic_RPX in action, check out the demonstration Rails application:
688
+ * <b>Live Demonstration Site:</b> [http://rails-authlogic-rpx-sample.heroku.com]
689
+ * <b>Demonstration site source repository:</b> [http://github.com/tardate/rails-authlogic-rpx-sample]
690
+
691
+
692
+ == Improving Authlogic_RPX: next steps; how to help
693
+
694
+ Authlogic_RPX is open source and hosted on {github}[http://github.com/tardate/authlogic_rpx]. Developer's are welcome to fork and play - if you have improvements or bug fixes, just send a request to pull from your fork.
695
+
696
+ If you have issues or feedback, please log them in the {issues list on github}[http://github.com/tardate/authlogic_rpx/issues]
697
+
698
+ Some of the improvements currently on the radar:
699
+ * Implement/verify support for RPX "paid" service features of their "Plus" and "Pro" accounts (to date, only tested with free RPX "Basic" account)
700
+
701
+
702
+ == Note on programmatically grabbing an authenticated session
703
+
704
+ If you need to programmatically perform proxy authentication as a specific user (e.g. to run a batch process on behalf of the user), authlogic provides the necessary capability and this can be used with RPX-authenticated users too:
705
+
706
+ app.get "/" # force Authlogic::Session::Base.controller activation
707
+ user = User.find(:first)
708
+ session = UserSession.create(user, true) # skip authentication and log the user in directly, the true means "remember me"
709
+ session.valid?
710
+ => true
711
+
712
+
713
+ == Internals
714
+
715
+ Some design principles:
716
+ * Attempted to stay as close to binarylogic's "unobtrusive authentication" sensibility in Authlogic design
717
+ * All direct RPX processing is handled in the AuthlogicRpx::Session class (not in the ActiveRecord model)
718
+ * It uses the plug-in architecture introduced in Authlogic v2.0.
719
+
720
+ ==== building the gem
721
+
722
+ * increment the version in lib/authlogic_rpx/version.rb
723
+ * update gem version refs in README.rdoc
724
+ * update CHANGELOG.rdoc
725
+
726
+ Build and distribute (the gemcutter way):
727
+
728
+ # update manifest file
729
+ $ rake manifest
730
+ # update gemspec
731
+ $ rake build_gemspec
732
+ # build the gem
733
+ gem build authlogic_rpx.gemspec
734
+ # push the gem to gemcutter (e.g. for version 1.0.3)
735
+ gem push authlogic_rpx-1.0.3.gem
736
+
737
+
738
+ == Kudos and Kopywrite
739
+
740
+ Thanks to {binarylogic}[http://github.com/binarylogic] for cleaning up authentication in rails by creating Authlogic in the first place and offering it to the community.
741
+
742
+ The idea of adding RPX support to authlogic is not new. Some early ideas were found in the following projects, although it was decided not to base this implementation on a fork of these, since the approaches varied considerably:
743
+ * <b>http://github.com/hunter/authlogic_rpx</b> an initial start, based on authlogic_openid and using rpx_now
744
+ * <b>http://github.com/gampleman/authlogic_rpx/</b> similar, but including an implementation of the RPX api
745
+
746
+ authlogic_rpx was created by Paul Gallagher (tardate.com) and released under the MIT license.
747
+ Big thanks for contributions from {John}[http://gitub.com/jjb] and {Damir}[http://gitub.com/sidonath]