sorcery

Magical Authentication for Rails 3 and Sinatra.

Inspired by restful_authentication, Authlogic and Devise. Crypto code taken almost unchanged from Authlogic. OAuth code inspired by OmniAuth and Ryan Bates’s railscasts about it.

Summary

Sorcery is a stripped-down, bare-bones authentication library, with which you can write your own authentication flow. It was built with a few goals in mind:

Less is more - less than 20 public methods to remember for the entire feature-set make the lib easy to ‘get’.
No built-in or generated code - use the library’s methods inside *your own* MVC structures, and don’t fight to fix someone else’s.
Magic yes, Voodoo no - the lib should be easy to hack for most developers.
Configuration over Confusion - 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.

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

Useful Links:

Example Rails 3 app using sorcery: github.com/NoamB/sorcery-example-app

Example Sinatra app using sorcery: github.com/NoamB/sorcery-example-app-sinatra

Documentation: rubydoc.info/gems/sorcery/0.3.0/frames

Check out the tutorials in the github wiki!

Installation:

If using bundler, first add ‘sorcery’ to your Gemfile:

gem “sorcery”

And run bundle install

Otherwise simply

gem install sorcery

Configuration:

config/application.rb

config.sorcery.submodules = [:user_activation, :remember_me] # add the submodules 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

app/models/user.rb (or another model of your choice, but a User class is assumed by default)

activate_sorcery! do |config|

	  config.user_activation_mailer = MyMailer

config.username_attribute_name = :email end

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

activate_sorcery! do |config|

	  config.session_timeout = 10.minutes

end

The configuration options vary with the submodules you’ve chosen to use, so check the documentation or the wiki tutorials regarding the specific submodule.

For your convenience, Sorcery includes a migrations generator for Rails, which can be used like so:

rails g sorcery_migration [list of submodules]

For example, for only the core functionality use:

rails g sorcery_migration core

To generate migrations for both the core AND ‘remember_me’ submodule:

rails g sorcery_migration core remember_me

These migrations use the default fields. You can choose to use these migrations or make your own tables and fields. Sorcery tries not to impose a database structure and naming scheme on your application.

Usage

Please see the tutorials in the github wiki.

Full Features List by module:

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

login/logout, optional return user to requested url on login, 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, method name, and attribute name.
configurable temporary token expiration.
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 temporary token 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.

Oauth (see lib/sorcery/controller/submodules/oauth.rb):

OAuth1 and OAuth2 support (currently twitter & facebook)
configurable db field names and authentications table.

Next Planned Features:

I’ve got many plans which include (by priority):

Scoping logins (to a subdomain or another arbitrary field)
Simple auth (no user)
Switching authentication mode at runtime (Maintenance mode)
Mongoid support
Configurable Auto login on registration/activation
Other reset password strategies (security questions?)
Other brute force protection strategies (captcha)
Have an idea? Let me know, and it might get into the gem!

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. I’ve used RSpec so far, please remain consistent with it.
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.

Contact

Feel free to ask questions using these contact details: email: [email protected] ( also for paypal ) twitter: @nbenari