Skip to content
Magical authentication for Rails 3 & 4
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Magical Authentication for Rails 3.

Inspired by restful_authentication, Authlogic and Devise. Crypto code taken almost unchanged from Authlogic.

Example app using sorcery:

Full Features List by module:

Core (see lib/sorcery/model/model.rb and lib/sorcery/controller/controller.rb):

  • login/logout, optional redirect on login to where the user tried to reach before, configurable redirect for non-logged-in users.

  • password encryption, algorithms: bcrypt(default), md5, sha1, sha256, sha512, aes256, custom(yours!), none. Configurable stretches and salt.

  • configurable attribute names for username, password and email.

User Activation (see lib/sorcery/model/submodules/user_activation.rb):

  • User activation by email with optional success email.

  • configurable attribute names.

  • configurable mailer.

  • Optionally prevent non-active users to login.

Reset Password (see lib/sorcery/model/submodules/reset_password.rb):

  • Reset password with email verification.

  • configurable mailer, method name, and attribute name.

  • configurable expiration.

  • configurable time between emails (hammering protection).

Remember Me (see lib/sorcery/model/submodules/remember_me.rb):

  • Remember me with configurable expiration.

  • configurable attribute names.

Session Timeout (see lib/sorcery/controller/submodules/session_timeout.rb):

  • Configurable session timeout.

  • Optionally session timeout will be calculated from last user action.

Brute Force Protection (see lib/sorcery/model/submodules/brute_force_protection.rb):

  • Brute force login hammering protection.

  • configurable logins before lock and lock duration.

Basic HTTP Authentication (see lib/sorcery/controller/submodules/http_basic_auth.rb):

  • A before filter for requesting authentication with HTTP Basic.

  • automatic login from HTTP Basic.

  • automatic login is disabled if session key changed.

Activity Logging (see lib/sorcery/model/submodules/activity_logging.rb):

  • automatic logging of last login, last logout and last activity time.

  • an easy method of collecting the list of currently logged in users.

  • configurable timeout by which to decide whether to include a user in the list of logged in users.


  • Modular design, load only the modules you need.

  • 100% TDD'd code, 100% test coverage.

Next Planned Features:

I've got many plans which include:

  • Configurable Auto login on registration/activation

  • Other reset password strategies (security questions?)

  • Other brute force protection strategies (captcha)

  • Sinatra support

  • Mongoid support

  • OAuth1 and OAuth2 support

  • Have an idea? Let me know, and it might get into the gem!

Project Goals:

This gem plugin was started out of a few personal goals which are not related to the problem solved by it at all:

  • I wanted to write something 100% TDD from start to finish.

  • I wanted to learn how to write an engine for Rails 3.

In addition to the above goals, when I decided this will be an authentication plugin, and while looking at existing solutions, these goals came up:

  • Simple & short configuration as possible, not drowning in syntactic sugar.

  • Keep MVC cleanly separated - DB is for models, sessions are for controllers. Models stay unaware of sessions.

  • Magic yes, Voodoo no.

  • No generated code polluting the application's code.

  • No built-in controllers, models, mailers, migrations or templates; Real apps will need all of these custom made.

Hopefully, I've achieved this. If not, let me know.


You can either git clone and then 'rake install' to live on the edge (unstable),

Or simply (stable):

gem install sorcery


First add 'sorcery' to your Gemfile:

gem “sorcery”

And run bundle install

There are 2 required places to configure the plugin, and an optional one:

  1. config/application.rb

config.sorcery.submodules = [:user_activation, :remember_me] # add the modules you want to use

You can also configure here any controller and any controller-submodule option here. For example:

config.sorcery.session_timeout = 10.minutes

  1. app/models/user.rb (or another model of your choice)

activate_sorcery! do |config|

	  config.user_activation_mailer = MyMailer

config.username_attribute_name = :email end

  1. app/controllers/application_controller.rb (OPTIONAL: this is actually needed only in some cases)

activate_sorcery! do |config|

	  config.session_timeout = 10.minutes


Also check the migrations in the example app to see what database fields are expected.

The configuration options vary with the modules you've chosen to use.

Contributing to sorcery

Your feedback is very welcome and will make this gem much much better for you, me and everyone else. Besides feedback on code, features, suggestions and bug reports, you may want to actually make an impact on the code. For this:

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Commit, do not mess with Rakefiles, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

If you feel my work has made your life easier, and you would like to thank me through a donation, my paypal email is in the contact details.


email: ( also for paypal ) twitter: @nbenari


Copyright © 2010 Noam Ben Ari ( See LICENSE.txt for further details. Released with permission from Kontera (, where I work.

Something went wrong with that request. Please try again.