RackWarden
RackWarden is a rack middleware mini-app that provides user authentication and management to any rack-based app (currently supports Sinatra and Rails, with more on the way). This project is in its infancy. It is currently a great starter to get you going with plug-in authentication for your ruby app. Over time it will grow into a more fully featured package while maintaining a focus on simplicity, modularity, and transparency.
RackWarden uses Sinatra for the mini-app, Warden for authentication, and DataMapper for database connections. It is based on the sinatra-warden-example at https://github.com/sklise/sinatra-warden-example. If you are new to Warden or Sinatra, I highly recommend downloading and experimenting with that example.
My goal in developing this software is to have drop-in authentication containing most of the features you see in user/account management sections of a typical web site. But I don't want to be strapped by this module in any of my projects, so it must be customizable. Or rather, overridable. The basics of this flexibility are already in place, and it will be a central theme throughout.
Please note that RackWarden is a work-in-progress. The gemspec, the files, the code, and the documentation can and will change over time. Follow on github for the latest fixes, changes, and developments.
What Does it Do?
RackWarden is a modular gatekeeper for your ruby web app. Once you enable RackWarden in your rack-based project, all routes/actions in your project will require a login and will redirect browsers to an authentication page. RackWarden provides its own view & layout templates to facilitate user authentication. RackWarden also provides it's own database & table structure to store user data. Views, layouts, databases, and tables are easily customized and/or overridden, however.
Once RackWarden authenticates a user, it gets out of the way, and the user is returned to your application. RackWarden also provides a number of user management tools for common actions like creating, updating, and deleting users.
Most of the RackWarden features can be customized. You can override the views, the database, the actions, and even the authentication logic with your own templates and code. The easiest (and possibly the most dramatic) customization is to provide RackWarden with your own layout template, giving RackWarden the appearane of the application you're integrating it with.
Installation
In your Gemfile:
gem 'rack_warden'
Then:
$ bundle
Or install manually:
$ gem install rack_warden
Usage
A few simple steps will have your entire app protected.
Sinatra
class MySinatraApp < Sinatra::Base
use RackWarden
get "/" do
erb "All routes are now protected"
end
end
Rails
application.rb or environment.rb
config.middleware.use RackWarden
# All routes are now protected
Configuration
RackWarden will look for a configuration file named rack_warden.yml in your project root or in your project/config/ directory.
---
database: sqlite3:///usr/local/some_other_database.sqlite3.db
layout: :'my_custom_layout.html.erb'
You an also pass configuration settings to RackWarden through the use
method of your framework. The params hash of use
will be translated directly to RackWarden's settings. In addition to RackWarden's specific configuration options, you can also pass in any standard Sinatra settings.
If you pass a block with the use
method, the block will be evaluated in the context of the RackWarden::App class. Anything you do in that block is just as if you were writing code in the app class itself. While in the block, you also have access to the current instance of RackWarden::App.
use RackWarden::App do |rack_warden_app_instance|
set :somesetting, 'some_value'
end
Configuration Options
Current list of settings specific to rack_warden, with defaults.
:layout
A symbol representing a layout file in any of the view paths.
layout: :'rack_warden_layout.html'
:default_route
A Sinatra route to fall back on after logout, errors, or any action that has no specified route.
default_route: '/'
:database_config
A database specification hash or or url string.
database_config: "sqlite:///Absolute/path/to/your/rack_warden.sqlite3.db"
# or
database_config:
adapter: mysql2
encoding: utf8
database: my_db_name
username: root
password: my_password
host: 127.0.0.1
port: 3306
:require_login
Parameters to pass to the before/before_filter for require_login. So if you're main app is Sinatra,
require_login: /^\/.+/
is the same as
class MySinatraApp
require_login /^\/.+/
end
which is the same as
class MySinatraApp
before /^\/.+/ do
require_login
end
end
For Rails, you would be passing a hash of :only or :except keys.
require_login:
except: :index
The default for :require_login is nil, which means require login on every route or action.
To disable automatic activation of require_login, pass it false
.
:allow_public_signup
Allows public access to the account creation view & action.
allow_public_signup: false
:recaptcha
Settings for Google's recaptcha service
:recaptcha => {
:sitekey => '',
:secret => ''
}
:log_path
File.join(Dir.pwd, 'log', 'rack_warden.log')
:user_table_name
nil
:views
File.("../views/", __FILE__)
Customization
Views
To customize RackWarden for your specific project, you can set :views to point to a directory within your project. Then create templates that match the names of RackWarden templates, and they will be picked up and rendered. RackWarden looks for templates at the top level of your views directory and in views/rack_warden (if it exists) as a default. You can change or add to this with the :views
setting.
use RackWarden::App, :views => File.join(Dir.pwd, 'app/views/another_directory')
Or if you simply want RackWarden to use your own custom layout, pass it a file path in the :layout parameter.
use RackWarden::App, :layout => :'layouts/rack_warden_layout.html'
Just remember that RackWarden is Sinatra, and any templates you pass must use Sinatra-specific code. For example, Sinatra uses url
instead of Rails' url_for
. Also remember that template names in Sinatra must always be symbols. Have a look at the readme on Sinatra's web site for more details on Sinatra's DSL.
Database
As a default, RackWarden will use a sqlite3 in-memory database (that starts fresh each time you boot your app). To use the database specified in your project, just pass :auto
to the :database_config
setting. Pass :file
to set up a sqlite3 database in your app's working directory. Or pass your own custom database specification (a url or hash). If you use a database other than sqlite3, you will need to include the respective DataMapper extension gems in your Gemfile or in your manually installed gem list. For MySQL, use dm-mysql-adapter, for Postgres use dm-postgres-adapter. See the DataMapper site for more info on database adapters.
# Database specification as a url
database_config: 'sqlite3:///path/to/my/database.sqlite3.db'
# Database specification as a hash
database_config: {adapter: 'sqlite3', database: '/path/to/my/database.sqlite3.db'}
# Use a remote MySQL database
database_config: {adapter: 'mysql', username: 'will', password: 'mypass',
host: 'somehost', database: 'my_database'}
# Format for database urls
#<adapter>://<username>:<password>@<host>:<port>/<database_name>