Rack::CookieAuth Build Status Dependency Status Code Climate

Rack::CookieAuth allows to log-in from a remember-me token stored in a cookie.

It depends on Active::Support >= 2.3.2 and is tested against Ruby 1.9.2, 1.9.3, ruby-head and the latest versions of Rubinius & JRuby.

Installation

Add this line to your application's Gemfile:

gem 'rack-cookie_auth'

And then execute:

$ bundle

Basic Usage

If you don't use Bundler, be sure to require Rack::CookieAuth manually before actually using the middleware:

 require 'rack/cookie_auth'
 use Rack::CookieAuth, cookie_secret: 'YOUR_SESSION_SECRET'

To use Rack::CookieAuth in your Rails application, add the following line to your application config file (config/application.rb or config/environments/production.rb) for Rails 3, config/environment.rb for Rails 2):

config.use Rack::CookieAuth, cookie_secret: 'YOUR_SESSION_SECRET'

# or if you're using Rack::Cache, be sure to insert Rack::CookieAuth before
config.middleware.insert_before Rack::Cache, Rack::CookieAuth, cookie_secret: 'YOUR_SESSION_SECRET'

Please note that the :cookie_secret option is mandatory!

Options

Cookie name

By default, the middleware will look for a cookie named "remember_user_token" but if your cookie is named otherwise, for instance "remember_admin_token", you can set it with the :cookie_name option:

config.middleware.use Rack::CookieAuth, cookie_secret: 'YOUR_SESSION_SECRET', cookie_name: 'remember_admin_token'

Redirection URL

By default, the middleware will redirect to the root path of the current domain but you can customize the redirection path with the :redirect_to option:

# It can be a path...
config.middleware.use Rack::CookieAuth, cookie_secret: 'YOUR_SESSION_SECRET', redirect_to: '/login'

# ... or a full URL
config.middleware.use Rack::CookieAuth, cookie_secret: 'YOUR_SESSION_SECRET', redirect_to: 'https://yourdomain.com/login'

Return to param key

By default, the middleware will redirect with a ?user_return_to param key with the requested url as value but you can customize the param key with the :return_to_param_key option:

config.middleware.use Rack::CookieAuth, cookie_secret: 'YOUR_SESSION_SECRET', return_to_param_key: 'admin_return_to'

# ... or avoid this param with nil
config.middleware.use Rack::CookieAuth, cookie_secret: 'YOUR_SESSION_SECRET', return_to_param_key: nil

Key in the Rack env for the current logged-in user ID

By default, the middleware will store the ID of the user retrieved from the cookie in env['user_id_key'] but if you want to use another key, for instance "admin_id_key", you can set it with the :user_id_key option:

config.middleware.use Rack::CookieAuth, cookie_secret: 'YOUR_SESSION_SECRET', user_id_key: 'admin_id_key'

Development

Pull requests are very welcome! Please try to follow these simple rules if applicable:

  • Please create a topic branch for every separate change you make.
  • Make sure your patches are well tested.
  • Update the README.
  • Update the CHANGELOG for noteworthy changes.
  • Please do not change the version number.

Author

Rémy Coutable (@rymai, rymai.me)

Contributors

https://github.com/jilion/rack-cookie_auth/graphs/contributors