Demonstrates the use of Rails with Authlogic and Authlogic_RPX gems for authentication. This sample is intended as a guide for developers who are interested in using Authlogic_RPX authentication in their own applications.
Authlogic_RPX is an Authlogic extension library that provides support for authentication using the Janrain Engage (formerly RPX) multi-authentication service offered by JanRain. To use RPX, you must first register your application at Janrain Engage. A free “Basic” account is available, in addition to paid enhanced versions. All work with Authlogic_RPX.
The demonstration Rails application is where you can see Authlogic_RPX in action:
Live Demonstration Site: [rails-authlogic-rpx-sample.heroku.com]
Demonstration site source repository: [github.com/tardate/rails-authlogic-rpx-sample]
Authlogic and RPX References
* Authlogic documentation: [rdoc.info/projects/binarylogic/authlogic] * Authlogic repo: [github.com/binarylogic/authlogic] * RPX documentation: [rpxnow.com/docs] * RPX_now gem repo: [github.com/grosser/rpx_now]
A full explanation of how to use Authlogic_RPX is included with the gem at [github.com/tardate/authlogic_rpx]. It would be useful to review this information first. The remainder of this document covers specific installation instructions for the sample, and highlights how various features are implemented in the sample.
Features of the sample
Here's a quick overview of what is in the sample, to give you an idea of where to go look and explore.
The sample application is a little example of a catalogue of articles, with the ability to comment on an article. Listings of articles and comments are public, but to create or edit you must be logged in.
The user management and authentication is handled by the following two domains in the application:
Users model, controller and associated views represent the registered application users. This model “acts_as_authentic”.
UserSession is the Authlogic session model and controller with associated views that handles authentication. The sample app supports both RPX authentication and conventional username-password authentication.
Features that are demonstrated:
Auto-registration via RPX (i.e. new users created automatically once they sign in via RPX)
Can register users with conventional username-password security (standard Authlogic support)
Users can add RPX authentication to conventional username-password accounts
Use of before_filter in controllers to restrict actions to authenticated users
Account mapping (Authlogic_RPX :internal mode) and account merging
Installing and Running the Sample
You can download and run this sample locally. It assumes you have the following setup already:
ruby and rails installed (rails 2.3.5 is used for the sample, but you should be able to use it with newer or older versions without too much trouble. It has been tested from rails 2.3.3 on)
git is not required to run the sample, but recommended if you want to work on authlogic enhancements or bugs
Here are the basic steps:
1. Obtain the sample
You can download a zip package of the sample from github
If you are using git, you can directly clone the sample repository:
$ git clone git://github.com/tardate/rails-authlogic-rpx-sample.git $ cd rails-authlogic-rpx-sample
Of course, if you are a github user, you can fork your own copy and work on that.
Whichever way you obtain the sample, unpack it if necessary and proceed from there.
2. Install the Authlogic gems
The easiest way is to use the rake task in the project
$ rake gems:install
3. Prepare the database
$ rake db:migrate
4. Obtain and set your Janrain Engage/RPX application key
To use Janrain Engage/RPX, you must first register your application at Janrain Engage. A free “Basic” account is available, in addition to paid enhanced versions. All work with Authlogic_RPX.
The sample application is configured to obtain the RPX API key and application name from environment keys called RARS_RPX_API_KEY and RARS_RPX_APP_NAME respectively. How you set this will depend on your operating system. for example:
$ RARS_RPX_API_KEY=13245_a_very_long_key_you_got_when_registering_at_rpxnow.com_12345 $ export RARS_RPX_API_KEY $ RARS_RPX_APP_NAME=the_application_name_you_registered_at_rpxnow.com $ export RARS_RPX_APP_NAME
Or if you are deploying this to a hosted service, follow the service provider's instructions. For example, to set the key for a deployment at heroku:
$ heroku config:add RARS_RPX_API_KEY=13245_a_very_long_key_you_got_when_registering_at_rpxnow.com_12345
Should be ready to go now!
$ ruby script/server => Booting WEBrick => Rails 2.3.3 application starting on http://0.0.0.0:3000 => Call with -d to detach => Ctrl-C to shutdown server [2009-09-26 22:02:00] INFO WEBrick 1.3.1 [2009-09-26 22:02:00] INFO ruby 1.8.6 (2008-08-11) [i386-mswin32] [2009-09-26 22:02:00] INFO WEBrick::HTTPServer#start: pid=5044 port=3000
Now access the site at localhost:3000
Using the sample to test a development release of authlogic_rpx
If you want to test modifications to the Authlogic_RPX gem you can make some changes to this sample to get it to load from your Authlogic_RPX development sources instead of the installed gem.
Replace the authlogic_rpx config.gem with a load_paths specification in config/environment.rb:
#config.gem 'authlogic_rpx', :version => '>= 1.1.0', :source => 'gemcutter.org' config.load_paths += %W( /experimental/authlogic_rpx/lib )
add an initializer to require authlogic_rpx. Create config/initializers/authlogic_rpx_test.rb containing:
Restart the server. The application will now be loading authlogic_rpx from the filesystem path you
specified with config.load_paths instead of from an installed gem.
Kudos and Kopywrite
Thanks to binarylogic for cleaning up authentication in rails by creating Authlogic in the first place and offering it to the community.
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: * github.com/hunter/authlogic_rpx an initial start, based on authlogic_openid and using rpx_now * github.com/gampleman/authlogic_rpx/ similar, but including an implementation of the RPX api