= Bolt

Bolt is yet another authentication/authorization plugin for Ruby on
Rails, implemented as a Rails Engine.  It is a full service plugin,
providing models, controllers, and views.

Authentication and Authorization are both provided by the plugin.
There is also support for working with any loaded class for
authentication, making it easy to authenticate with an external source
such as LDAP.


== Status

As of December 29, 2008:

Bolt is currently being used in production.  It has a health set of
unit and functional tests that are all passing for Rails 1.2.6.  I'm
currently working on some small changes to get all tests for Rails
2.2.2 passing.


== Creating Users

Bolt uses a table called identities that might look very similar to
your users table.  The duplication is necessary to support different
authentication sources.  It also means that when you create a new user
record, you must also create a new Bolt identity record.

This is done using the +create_bolt_identity+ method on your user
object.  Documentation for method can be found in Bolt::UserModelExt.

Also see the script/createuser script for an example of how to
create a user and identity.

In a future version of Bolt, identity creation will be automatic and
you won't need to call +create_bolt_identity+.


== Authentication

The Bolt plugin provides a SessionsController that performs the work
of authenticating and logging a user in.  You can request that a user
be authenticated by using the +require_authentication+ class method in
your controller.

See Bolt::Authentication::ClassMethods for more details about
requesting that authentication happen.

There are a few authentication state helper methods added to all your
controllers and views.  You can read about these helpers in
Bolt::State.  These helpers include +current_user+.


== Authorization

Authorization is achieved through roles. Users are associated with
roles, and roles have specific permissions.  Each user can optionally
be associated with one or more roles, and a role can have any number
of permissions.

There are a number of authorization helper methods that are added to
your user model class.  You can find out more information about these
methods, such as <tt>can?</tt> in the Bolt::UserModelExt
module.

You can have your controller perform authorization by using the
+require_authorization+ class method.  

For more specific information about authorization, please see
Bolt::Authorization.


== Authenticating With an External Source

1. Write a class that looks like the Identity class
2. Set Bolt::Config.backend


== History

Bolt is a derivative of Peter Jones' Rauth plugin for Rails, which
itself was taken from the Devalot Rails application.


== Rauth Comparison

Since Bolt is derived from Rauth, it might be useful to compare the
two.  The biggest difference is that Bolt is a Rails Engine, whereas
Rauth is a traditional Rails plugin.

Bolt is also greatly simplified.  The bridge and account creator code
has been removed, and all configuration options have been moved to a
single class (Bolt::Config).

Rauth limited you to one role per person.  Bolt allows a single user
to belong to many roles.  This is more in-line with the Unix group
philosophy.


== Converting from Rauth

A conversion script is in the works.  Stay tuned.


== Credits

The primary author and maintainer of Bolt is Peter Jones.  Bolt is an
open source project, and has thus has received help from many
developers:

* Eric Harris-Braun