Skip to content
Generates common user authentication code for Rails/Merb, with a full test/unit and rspec suite and optional Acts as State Machine support built-in.
Branch: rails3
Clone or download
Pull request Compare This branch is 8 commits ahead, 24 commits behind technoweenie:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Restful Authentication Generator

This widely-used plugin provides a foundation for securely managing user authentication:

  • Login / logout
  • Secure password handling
  • Account activation by validating email
  • Account approval / disabling by admin
  • Rudimentary hooks for authorization and access control.

Several features were updated in May, 2008.

!! important: if you upgrade your site, existing user account !!
!! passwords will stop working unless you use --old-passwords !!

Issue Tracker

Please submit any bugs or annoyances at


This page has notes on

See the wiki (or the notes/ directory) if you want to learn more about:

These best version of the release notes are in the notes/ directory in the source code — look there for the latest version. The wiki versions are taken (manually) from there.

Exciting new features


There are now Cucumber features that allow expressive, enjoyable tests for the authentication code. The flexible code for resource testing in stories was extended from Ben Mabey’s.

Modularize to match security design patterns:

  • Authentication (currently: password, browser cookie token, HTTP basic)
  • Trust metric (email validation)
  • Authorization (stateful roles)
  • Leave a flexible framework that will play nicely with other access control / policy definition / trust metric plugins


  • Added a few helper methods for linking to user pages
  • Uniform handling of logout, remember_token
  • Stricter email, login field validation
  • Minor security fixes — see CHANGELOG

Non-backwards compatible Changes

Here are a few changes in the May 2008 release that increase “Defense in Depth”
but may require changes to existing accounts

  • If you have an existing site, none of these changes are compelling enough to warrant migrating your userbase.
  • If you are generating for a new site, all of these changes are low-impact. You should apply them.


The new password encryption (using a site key salt and stretching) will break existing user accounts’ passwords. We recommend you use the --old-passwords
option or write a migration tool and submit it as a patch. See the Tradeoffs note for more information.


By default, email and usernames are validated against a somewhat strict pattern; your users’ values may be now illegal. Adjust to suit.


This is a basic restful authentication generator for rails, taken from acts as authenticated. Currently it requires Rails3 beta.

IMPORTANT FOR RAILS > 2.1 USERS To avoid a NameError exception (lighthouse tracker ticket), check out the code to have an underscore and not dash in its name:

If you’re using git as your source control, you have three options.

  • Install as a plugin
    rails plugin install git:// restful_authentication
  • Checkout into vendor/plugins using
    git clone git:// restful_authentication
    and delete the .git folder inside the directory. (This will break the connection with the github repository, and allow you to include the code into your project with git add)
  • Use git submodule. From the top level of your project, add the plugin
    git submodule add git:// vendor/plugins/restful_authentication
    This will create a reference link to the repository, which can be save into your project. You will need to let capistrano know that you want to update submodules on deploy via set :git_enable_submodules, 1.

git-submodule docs

To use the generator:

  rails g authenticated user sessions \
    --include-activation \
    --stateful \
    --rspec \
    --skip-migration \
    --skip-routes \

  • The first parameter specifies the model that gets created in signup (typically a user or account model). A model with migration is created, as well as a basic controller with the create method. You probably want to say “User” here.
  • The second parameter specifies the session controller name(options default to sessionsController). This is the controller that handles the actual login/logout function on the site. (probably: “Session”).
  • --include-activation: Generates the code for a ActionMailer and its respective Activation Code through email.
  • --stateful: Builds in support for acts_as_state_machine and generates activation code. (--stateful implies --include-activation). Based on the idea at Passing --skip-migration will skip the user migration, and --skip-routes will skip resource generation both useful if you’ve already run this generator. (Needs the acts_as_state_machine plugin, but new installs should probably run with --aasm instead.)
  • --aasm: Works the same as stateful but uses the updated aasm gem
    Add gem 'rubyist-aasm', :require => 'aasm' to Gemfile for use in projects that use rails3-beta
  • --rspec: Generate RSpec tests and Stories in place of standard rails tests. This requires the RSpec-2 for Rails-3, run gem install rspec-rails --pre to install RSpec-2 for Rails-3(make sure you rails g rspec:install after installing RSpec.) The rspec and story suite are much more thorough than the rails tests, and changes are unlikely to be backported.
  • --old-passwords: Use the older password scheme (see [[#COMPATIBILITY]], above)
  • --skip-migration: Don’t generate a migration file for this model
  • --skip-routes: Don’t generate a resource line in config/routes.rb

After installing

The below assumes a Model named ‘User’ and a Controller named ‘Session’; please alter to suit. There are additional security minutae in notes/README-Tradeoffs — only the paranoid or the curious need bother, though.

  • Add these familiar login URLs to your config/routes.rb if you like:
     match 'login' => 'sessions#new', :as => :login
     match 'logout' => 'sessions#destroy', :as => :logout
     match 'signup' => 'users#new', :as => :signup
  • With --include-activation, also add to your config/routes.rb:
    match 'activate/:activation_code' => 'users#activate', :as => :activate, :activation_code => nil

    and add an observer to config/application.rb:
    config.active_record.observers = :user_observer

    Pay attention, may be this is not an issue for everybody, but if you should have problems, that the sent activation_code does match with that in the database stored, reload your user object before sending its data through email something like:
    class UserObserver < ActiveRecord::Observer
      def after_create(user)
      def after_save(user)
        UserMailer.deliver_activation(user) if user.recently_activated?
  • With --stateful, add an observer to config/environment.rb:
    config.active_record.observers = :user_observer

    and modify the users resource line in config/routes.rb to read
    resources :users do
      member do
        put :suspend
        put :unsuspend
        delete :purge
  • If you use a public repository for your code (such as github, rubyforge, gitorious, etc.) make sure to NOT post your site_keys.rb (add a line like ‘/config/initializers/site_keys.rb’ to your .gitignore or do the svn ignore dance), but make sure you DO keep it backed up somewhere safe.
You can’t perform that action at this time.