OpenID Authentication for Hobo
===============================

This plugin provides a drop-in replacement authentication system for
Hobo (http://hobocentral.net/). Instead of using password based
authentication, it uses a decentralized sign-in system called OpenID
(http://openid.net/).

An important difference between this function and Hobo's built in user
management is that this plugin does not provide a signup url. Instead,
users are allowed to log in without signing up first. When a user logs
in for the first time a new user account will automatically be
created. You can optionally use simple registration to have that new
account filled with information about the new user, also
automatically.

If you want to allow multiple OpenID URLs to be associated with a
single user, all you need to do is override the method
find_by_identity_url in your user model. You will need to set it up so
that it returns a given user record when passed any of that user's
OpenID URLs.


Known Bugs
==========

This plugin is currently not compatible with the latest version of
Hobo. I plan to update it eventually.


Installing
===========

- Install Hobo plugin from hobocentral.net
- Install the ruby-openid and ruby-yadis gems.
- Unpack the plugin in your vendor/plugins directory.


Setting up
==========

This plugin works basically the same way authenticated user support
works in Hobo. There are just a couple of extra things you will need
to set up. Here is the process in its entirety:


Create a user model
-------------------

Run this command to use Hobo's generation scripts to create a user
model:

    script/generate hobo_user_model User

You can replace User with a different name, if you want to.

Open app/models/user.rb to remove these lines:

    hobo_model

    include Hobo::AuthenticatedUser

    set_login_attr :username

and replace them with this one:

    hobo_openid_user_model :openid

Replace openid with the name of the database column you will be using
to store identity urls. That will also be the login attribute for this
model.

The database table for your user model will need to have these
columns:

    table.string   :openid
    table.string   :remember_token
    table.datetime :remember_token_expires_at

Again, replace openid with whatever you want to use.

If you want to set up simple registration, see the simple registration
section at the end of this file.


Create a users controller
-------------------------

Create a controller - either manually or using a generation
script. Put this line in it:

    hobo_openid_user_controller User

User is optional. You can leave that out if the name of the controller
is the plural of the name of the user model. Or you can change it to
the name of your user model.

The controller does not need to contain anything other than that
single line. Basic actions will be defined automatically.

If the controller contains this line, make sure to remove it:

   hobo_user_controller


Add filters to application.rb
-----------------------------

Add this line to app/controllers/application.rb:

    before_filter :login_required

If you want the option of having users signed in for up to two weeks
at a time, add this line above the previous one:

    before_filter :login_from_cookie


Create routes
-------------

Add this line to config/routes.rb:

    Hobo.add_openid_routes(map)


Create a login page
-------------------

Hobo's default login page will work fine. It's just that the password
field won't do anything. You will probably want to customize this
field to remove it.

If you want to create your own login page, all that it requires is a
form with a single field that submits a parameter called "login". 

You can also optionally add a checkbox that submits a "remember_me"
parameter. If you do, when a user checks the box before logging in
that user will stay signed in for two weeks if you also included the
:login_from_cookie before_filter in your application controller.


Simple Registration
===================

Simple registration is a part of the OpenID protocol that is intended
to make signing up with a web application really fast. Using this
plugin, when a user signs in for the first time a new account is
automatically created. If you define simple registration mappings in
your user model, the plugin will ask the user's OpenID provider for
the simple registration parameters specified. The responses will be
entered into the new user record in the database columns you specify
in the mappings.

To define some simple registration mappings, add a line like this to
your user model:

    set_simple_registration_mappings :optional => { :email => :email,
                                                    :fullname => :full_name,
                                                    :timezone => :time_zone }

These mappings will cause the plugin to ask for the user's email
address, full name, and time zone. When the user logs into your
application for the first time, she will see a screen on her OpenID
providers web site asking her if she wants to log into your
application. She will also be told what information your application is
asking for, and she will be given an opportunity to enter that
information.

If your user does enter the requested information, it will be recorded
in the database in her user record. Using the above mappings, her
email address will be stored in the email column, her name will be
stored in the full_name column, and her time zone will be stored in
the time_zone column.

You can specify that certain information is required, instead of
optional, with another line like this:

    set_simple_registration_mappings :required => { ... }
    set_simple_registration_mappings :optional => { ... }

Note that specifying that information is required does not guarantee
that your application will get it. It is a way for you to inform the
user that if that information is not provided, she won't be allowed to
sign up. You will have to define validations for required information
yourself though.

Here are all of the simple registration parameters that you can use:

    email, nickname, fullname, dob, gender, postcode, country,
    timezone, language


Policy URL
==========

If you decide to use simple registration, it might also be a good idea
to provide a policy URL. This is a URL for a page that describes your
policy about handling users' personal information. Most users will
feel more comfortable using your application if they are assured that
their information will be kept private.

If you specify a policy URL, then when the user is asked for simple
registration information she will also be shown a link to your
policy. If you do not provide a policy URL, some providers will show a
message to the user warning that you did not provide a privacy policy.

There are two ways to provide a policy URL to your users. The first is
to create a named route called "policy", by adding a line like this to
config/routes.rb:

    map.policy 'privacy_policy', :controller => 'front', :action => 'policy'

The other method is to override the login action in your user
controller. In the new version of login you should call hobo_login and
pass something like :policy_url => url_for(:action => 'policy') as an
argument. This method will take precedence over the named route, if
you use both methods.