You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Peter J. Jones 0f9a59b7eb Don't raise an exception when updating user_name 10 years ago
app Activation and password changing fixes 10 years ago
db/migrate initial commit, copying code from Rauth and moving it around a bit 11 years ago
doc More documentation updates 10 years ago
generators Add some generators 10 years ago
lib Don't raise an exception when updating user_name 10 years ago
script update copyright 11 years ago
test Get tests to pass again after engines upgrade 10 years ago
ChangeLog Help tests pass, and clean up the change log. 11 years ago
LICENSE update copyright 11 years ago
README More documentation updates 10 years ago
TODO Update TODO, comment out forced forgery protection 10 years ago
init.rb update copyright 11 years ago
routes.rb Fix a test and a route 11 years ago


= 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

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

For more specific information about authorization, please see

== 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

== 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

* Eric Harris-Braun