= Janus

Janus is an authentication engine for Ruby on Rails 3+ to painlessly handle
users in your apps. It comes with everything needed, from the migrations to the
controllers, plus some different strategies to keep user signed in.

Janus also tries to be somewhat compatible with Devise's API and conventions,
because there was no reason to change it completely. Thought there are some
differences, like controllers and views being required in your apps, and emails
being sent from the controllers and never from the models.

== Features

- full auth system with strategies and hooks;
- scoped auth for parallel authentications (like +users+, +admin_users+, etc.);
- abstract controllers ready to use;
- generators to have everything generated automatically;
- use only what you need at anytime.

As for the strategies and hooks:

- {DatabaseAuthenticatable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/DatabaseAuthenticatable]
  to auth users with passwords (plus registration and password reset);
- {RemoteAuthenticatable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/RemoteAuthenticatable]
  to keep users signed in across top level domains;
- {Confirmable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/RemoteAuthenticatable]
  to have users confirm their emails upon registration;
- {Rememberable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/Rememberable]
  to keep users authentified;
- {Trackable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/Trackable]

== Getting Started

First add the janus gem to your Gemfile, then run `bundle` to install it:

  gem 'janus'
  gem 'bcrypt-ruby'
  # gem 'scrypt'

You'll also need either the `bcrypt-ruby` or scrypt` gems, depending on which
library you want to use to encrypt the passwords. Janus uses bcrypt by default,
to be compatible with Devise, but you may prefer scrypt, which is stronger.

Run the <tt>janus:install</tt> generator to setup janus in your app:

  $ rails generate janus:install

Then create your first authenticatable resource, let's say +User+:

  $ rails generate janus:resource user

You may notice that Janus also generates all the controllers and views. This is
because you will eventually need those to customize some behavior and having
them around from the beginning is great.

You may run the routes rake task, to see what routes were added by Janus.

=== Helpers & Filters

  - authenticate_user!
  - user_signed_in?
  - current_user

=== Strategies

You may customize the strategies for the <tt>janus:resource</tt> generator, like an
AdminUser that may only be created and managed from the console:

  $ rails generate janus:resource AdminUser session password remember

Here is the list of all the current strategies:

- +session+      — get users signed in and out (email/password combinaison)
- +remember+     — keep users signed in across sessions
- +registration+ — get users registered
- +confirmation+ — emails may be confirmed after registration
- +password+     — reset password (using an email exchanged token)
- +track+        — track current and previous user's sign in date and IP
- +remote+       — keeps users signed in different top level domains


== TODO

- Differenciate mailers per resource, by looking for User::Mailer or AdminUser::Mailer classes.
- Reconfirmable when email changes.
- Simple configuration to use scrypt instead of bcrypt for password encryption.
- TokenAuthenticatable strategy.
- Rememberable across top level domains.
- Omniauthable (or shall we let the user do it himself?)
- Providing an OAuth 1.0 service whould be cool.

== License

Janus is distributed under the MIT-License.

== Credits

Most of the API and some code like password encryption is copied from
Devise: http://github.com/plataformatec/devise.git and Warden:
http://github.com/hassox/warden

- Julien Portalier <julien@portalier.com>