authenticate 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 95466d6fe7aaa95a7157ca870d2cb7324a11aacf
-  data.tar.gz: f10ec192418dff2700252c2c37c99ff0324c18ba
+  metadata.gz: 1233e7491c83dd3155f5546e45fe6de01e3dfba3
+  data.tar.gz: 8cf747a94820850842e2ae37137a2be1bdd22f6a
 SHA512:
-  metadata.gz: 137399918e6cad2a327fde6bda5c724192d10cc52b7c5682814773641662ab4b58808a48a7a3076e1baf9dde108cc4db942675bdf3072177aa8ab3cb6dc489a8
-  data.tar.gz: be34b75f473e5f0ae869c0859710a158c87a92d02bd5d2166d0ebe9527ce02eb58458027bdc1133665d2ee3be4148ddd58cbfeac14618ea548e4156fe76a6973
+  metadata.gz: 578c426daca72149a48eea0340da3df6c98dda9df0707eef6479dc9aa2b622ccfe113ab16a2cfe1bf693974368545af190710371f29959108b01bc6b40cd408b
+  data.tar.gz: 70817ffbf340daa66078abf00b427412e6bec84b8257c4fd5d1f5fa30ed200718f2b6bd73c81c72b8dc58d7f1c520ed95c890080b6c91e615d0e3054ad7aa353

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Authenticate Changelog
+
+
+## [0.2.0] - February 2, 2016
+
+Added app/ including controllers, views, routes, mailers.
+
+
+## [0.1.0] - January 23, 2016
+
+Initial Release, barely functioning

data/Gemfile

@@ -1,10 +1,6 @@
 source 'https://rubygems.org'
 
 gem 'rails'
-gem 'sqlite3'
-gem 'pry'
-gem 'factory_girl_rails'
-# gem 'capybara'
 
 # Declare your gem's dependencies in authenticate.gemspec.
 # Bundler will treat runtime dependencies like base dependencies, and

data/Gemfile.lock

@@ -104,10 +104,6 @@ GEM
       rake (>= 0.8.7)
       thor (>= 0.18.1, < 2.0)
     rake (10.4.2)
-    rspec (3.1.0)
-      rspec-core (~> 3.1.0)
-      rspec-expectations (~> 3.1.0)
-      rspec-mocks (~> 3.1.0)
     rspec-core (3.1.7)
       rspec-support (~> 3.1.0)
     rspec-expectations (3.1.2)
@@ -146,7 +142,6 @@ DEPENDENCIES
   factory_girl_rails
   pry
   rails
-  rspec
   rspec-rails
   sqlite3
 

data/README.md

@@ -7,21 +7,79 @@ open to significant modification.
 
 Authenticate is inspired by, and draws from, Devise, Warden, Authlogic, Clearance, Sorcery, and restful_authentication.
 
+Please use [GitHub Issues] to report bugs.
+
+[GitHub Issues]: https://github.com/tomichj/authenticate/issues
+
+
+
+## Philosophy
+
+* simple - Authenticate's code is straightforward and easy to read.
+* opinionated - set the "right" defaults, but let you control almost everything if you want
+* small footprint - as few public methods and modules as possible
+* configuration driven - almost all configuration is performed in the initializer
+
+
+
+## Implementation Overview
+
+Authenticate:
+* loads modules into your user model to provide authentication functionality
+* loads `callbacks` that are triggered during authentication and access events. All authentication
+decisions are performed in callbacks, e.g. do you have a valid session, has your session timed out, etc.
+* loads a module into your controllers (typically application controller) to secure controller actions 
+
+The callback architecture is based on the system used by devise and warden, but significantly simplified.
+
+
+### Session Token
+
+Authenticate generates and clears a token (called a 'session token') to identify the user from a saved cookie.
+When a user authenticates successfully, Authenticate generates and stores a 'session token' for your user in 
+your database. The session token is also stored in a cookie in the user's browser. 
+The cookie is then presented upon each subsequent access attempt to your server.
+
+### User Model
+
+
+
 
 ## Install
 
-Installation is pretty standard. Authenticate does not currently have an automated install process. One is coming.
+To get started, add Authenticate to your `Gemfile`:
 
-* Include `Authenticate::User` into your `User` model.
-* Include `Authenticate::Controller` into your `ApplicationController`
-* Add an initializer: config/intializers/authenticate.rb containing:
-    Authenticate.configure do |config|
-      # any settings you wish to tweak, see below
-    end
-* Create a migration for any Authenticate features you wish to take advantage of. Here's a good default:
-    `rails g migration AddAuthenticateToUsers email:string encrypted_password:string session_token:string 
-    session_expiration:datetime sign_in_count:integer last_sign_in_at:datetime last_sign_in_ip:string 
-    last_access_at:datetime current_sign_in_at:datetime current_sign_in_ip:string`
+```ruby
+gem 'authenticate'
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Then run the installation generator:
+
+```sh
+rails generate authenticate:install
+```
+
+The generator does the following:
+
+* Insert `include Authenticate::User` into your `User` model.
+* Insert `include Authenticate::Controller` into your `ApplicationController`
+* Add an initializer at `config/intializers/authenticate.rb`.
+* Create migrations to either create a users table or add additional columns to :user. A primary migration is added,
+'create users' or 'add_authenticate_to_users'. This migration is required. Two additonal migrations are created
+to support the 'brute_force' and 'timeoutable' modules. You may delete the brute_force and timeoutable migrations,
+but those migrations are required if you use those Authenticate features (see Configure, next).
+
+Finally, you'll need to run the migrations that Authenticate just generated:
+
+```sh
+rake db:migrate
+```
 
 
 ## Configure
@@ -30,18 +88,22 @@ Override any of these defaults in your application `config/initializers/authenti
 
 ```ruby
 Authenticate.configure do |config|
-    config.user_model = 'User'
-    config.cookie_name = 'authenticate_session_token'
-    config.cookie_expiration = { 1.year.from_now.utc }
-    config.cookie_domain = nil
-    config.crypto_provider = Bcrypt
-    config.timeout_in = nil  # 45.minutes
-    config.max_session_lifetime = nil  # 8.hours
-    config.max_consecutive_bad_logins_allowed = nil # 5
-    config.bad_login_lockout_period = nil # 5.minutes
-    config.authentication_strategy = :email
+  config.user_model = 'User'
+  config.cookie_name = 'authenticate_session_token'
+  config.cookie_expiration = { 1.year.from_now.utc }
+  config.cookie_domain = nil
+  config.cookie_path = '/
+  config.secure_cookie = false
+  config.http_only = false
+  config.crypto_provider = Bcrypt
+  config.timeout_in = nil  # 45.minutes
+  config.max_session_lifetime = nil  # 8.hours
+  config.max_consecutive_bad_logins_allowed = nil # 5
+  config.bad_login_lockout_period = nil # 5.minutes
+  config.authentication_strategy = :email
 ```
 
+Configuration parameters are described in detail here: [Configuration](lib/authenticate/configuration.rb)
 
 
 ### timeout_in
@@ -53,7 +115,6 @@ If the interval between the current access time and the last access time is grea
 the session is invalidated. The user will be prompted for authentication again.
 
 
-
 ### max_session_lifetime
 
 * max_session_lifetime: the maximum interval a session is valid, regardless of user activity.
@@ -63,7 +124,6 @@ max_session_lifetime. The user session is invalidated and the next access will w
 authentication again.
 
 
-
 ### max_consecutive_bad_logins_allowed & bad_login_lockout_period
 
 * max_consecutive_bad_logins_allowed: an integer
@@ -74,7 +134,6 @@ The user's consecutive bad logins will be tracked, and if they exceed the allowe
 will be locked. The lock will last `bad_login_lockout_period`, which can be any time period (e.g. `10.minutes`).  
 
 
-
 ### authentication_strategy
 
 The default authentication strategy is :email. This requires that your User model have an attribute named `email`.
@@ -85,50 +144,18 @@ You may instead opt for :username. The username strategy will identify users wit
 The strategy will also add username attribute validation, ensuring the username exists and is unique.
 
 
+
 ## Use
 
 ### Authentication
 
-To perform authentication use:
-
-* authenticate(params) - authenticate a user with credentials in params, return user if correct. 
-`params[:session][:email]` and `params[:session][:password]` are required for the :email authentication
-strategy. `params[:session][:username]` and `params[:session][:password]` are required for
-the :username authentication strategy.
-
-* login(user, &block) - log in the just-authenticated user. Login will run all rules as provided in the configuration,
-such as timeout_in detection, max_session_lifetime, etc. You can provide a block to this method to handle the result.
-Your block will receive either {SuccessStatus} or {FailureStatus}.
-
-An example session controller:
+Authenticate provides a session controller and views to authenticate users. After successful authentication, 
+the user is redirected to the path they attempted to access, or as specified by the `redirect_url` property
+ in your configuration. This defaults to '/' but can customized:
 
 ```ruby
-class SessionsController < ActionController::Base
-  include Authenticate::Controller
-
-  def create
-    user = authenticate(params)
-    login(user) do |status|
-      if status.success?
-        flash[:notice] = 'You successfully logged in! Very nice.'
-        logger.info flash[:notice].inspect
-        redirect_to '/'
-      else
-        flash[:notice] = status.message
-        logger.info flash[:notice].inspect
-        render template: 'sessions/new', status: :unauthorized
-      end
-    end
-  end
-
-
-  def new
-  end
-
-  def destroy
-    logout
-    redirect_to '/', notice: 'You logged out successfully'
-  end
+Authenticate.configure do |config|
+  config.redirect_url = '/specials'
 end
 ```
 
@@ -153,7 +180,7 @@ Example:
 ```erb
 <% if authenticated? %>
   <%= current_user.email %>
-  <%= button_to "Sign out", sign_out_path, method: :delete %>
+  <%= link_to "Sign out", sign_out_path %>
 <% else %>
   <%= link_to "Sign in", sign_in_path %>
 <% end %>
@@ -173,23 +200,64 @@ end
 ```
 
 
+## Overriding Authenticate
+
+### Views
+
+You can quickly get started with a rails application using the built-in views. See [app/views](/app/views) for
+the default views. When you want to customize an Authenticate view, create your own copy of it in your app.
+
+You can use the Authenticate view generator to copy the default views into your application: 
+
+```sh
+$ rails generate authenticate:views
+```
+
+
+### Controllers
+
+If the customization at the views level is not enough, you can customize each controller, and the
+authenticate mailer. See [app/controllers](/app/controllers) for the default controllers, and 
+[app/mailers](/app/mailers) for the default mailer. 
+
+You can use the Authenticate controller generator to copy the default controllers and mailer into your application:
+
+```sh
+$ rails generate authenticate:controllers
+```
+
+
+### Routes
+
+Authenticate adds routes. See [config/routes.rb](/config/routes.rb) for the default routes.
+
+If you want to control and customizer the routes, you can turn off the built-in routes in
+the Authenticate configuration with `config.routes = false`.
+
+You can optionally run a generator to dump a copy of the default routes into your application for modification.
+
+```sh
+$ rails generate authenticate:routes
+```
+
+
 ## Extending Authenticate
 
-Authenticate can be extended with two mechanisms:
+Authenticate can be further extended with two mechanisms:
 
 * user modules: add behavior to the user model
-* callbacks: add login during various authentication events, during login and access
-
+* callbacks: add behavior during various authentication events, such as login and subsequent hits
 
 
 ### User Modules
 
-Add behavior to your User model for your callbacks to use. Include them yourself directly in your User class,
-or via the Authentication configuration. 
+Add behavior to your User model for your callbacks to use. You can, of course, incldue behavrio yourself directly 
+in your User class, but you can also use the Authenticate module loading system.
+
+To add a custom module to Authenticate, e.g. `MyUserModule`: 
 
-Example:
 ```ruby
-Authenticate.configuraton do |config|
+Authenticate.configuration do |config|
   config.modules = [MyUserModule]
 end
 ```
@@ -197,38 +265,41 @@ end
 
 ### Callbacks
 
-Callbacks can be added with `after_set_user` or `after_authentication`. See {Authenticate::Lifecycle} for full details.
+Callbacks can be added to Authenticate. Use `Authenticate.lifecycle.after_set_user` or 
+`Authenticate.lifecycle.after_authentication`. See [Lifecycle](lib/authenticate/lifecycle.rb) for full details.
 
-Callbacks can `throw(:failure, message)` to signal an authentication/authorization failure, or perform
+Callbacks can `throw(:failure, message)` to signal an authentication/authorization failure. Callbacks can also perform
 actions on the user or session. Callbacks are passed a block at runtime of `|user, session, options|`.
 
-
-Example that counts logins for users. It consists of a module for User, and a callback that is
+Here's an example that counts logins for users. It consists of a module for User, and a callback that is
 set in the `included` block. The callback is then added to the  User module via the Authenticate configuration.
 
 ```ruby
+# app/models/concerns/login_count.rb
 module LoginCount
   extend ActiveSupport::Concern
 
-  included do
-    # authentication hook
+  included do    
+    # Add a callback that is triggered after every authentication
     Authenticate.lifecycle.after_authentication name:'login counter' do |user, session, options|
       user.count_login if user
     end
   end
 
   def count_login
+    self.login_count ||= 0
     self.login_counter += 1
   end
 end
 
-Authenticate.configiration do |config|
+# config/initializers/authenticate.rb
+# You could also just `include LoginCount` in your user model.
+Authenticate.configuration do |config|
   config.modules = [LoginCount]
 end
 ```
 
 
-
 ## Testing
 
 Authenticate has been tested with rails 4.2, other versions to follow.

data/app/controllers/authenticate/passwords_controller.rb

@@ -0,0 +1,130 @@
+# Request password change via an emailed link with a unique token.
+# Thanks to devise and Clearance.
+class Authenticate::PasswordsController < ApplicationController
+  skip_before_action :require_authentication, only: [:create, :edit, :new, :update], raise: false
+  before_action :ensure_existing_user, only: [:edit, :update]
+
+  # Display screen to request a password change email.
+  # GET /users/passwords/new
+  def new
+    render template: 'passwords/new'
+  end
+
+  # Send password change email.
+  #
+  # POST /users/password
+  def create
+    if user = find_user_for_create
+      user.forgot_password!
+      deliver_email(user)
+    end
+    redirect_to sign_in_path, notice: flash_create_description
+  end
+
+  # Screen to enter your new password.
+  #
+  # GET /users/passwords/3/edit?token=abcdef
+  def edit
+    @user = find_user_for_edit
+    if !@user.reset_password_period_valid?
+      redirect_to sign_in_path, notice: flash_failure_token_expired
+    else
+      render template: 'passwords/edit'
+    end
+  end
+
+  # Save the new password entered in #edit.
+  #
+  # PUT /users/passwords/3/
+  def update
+    @user = find_user_for_update
+
+    if !@user.reset_password_period_valid?
+      redirect_to sign_in_path, notice: flash_failure_token_expired
+    elsif @user.update_password password_reset_params
+      login @user
+      redirect_to url_after_update, notice: flash_success_password_changed
+    else
+      # failed to update password for some reason
+      flash.now[:notice] = flash_failure_after_update
+      render template: 'passwords/edit'
+    end
+  end
+
+  private
+
+  def deliver_email(user)
+    mail = ::AuthenticateMailer.change_password(user)
+
+    if Gem::Version.new(Rails::VERSION::STRING) >= Gem::Version.new('4.2.0')
+      mail.deliver_later
+    else
+      mail.deliver
+    end
+  end
+
+  def password_reset_params
+    params[:password_reset][:password]
+  end
+
+  def find_user_for_create
+    Authenticate.configuration.user_model_class.find_by_email params[:password][:email]
+  end
+
+  def find_user_for_edit
+    find_user_by_id_and_password_reset_token
+  end
+
+  def find_user_for_update
+    find_user_by_id_and_password_reset_token
+  end
+
+  def ensure_existing_user
+    unless find_user_by_id_and_password_reset_token
+      flash.now[:notice] = flash_failure_when_forbidden
+      render template: 'passwords/new'
+    end
+  end
+
+  def find_user_by_id_and_password_reset_token
+    Authenticate.configuration.user_model_class.where(id: params[:id], password_reset_token: params[:token].to_s).first
+  end
+
+  def flash_create_description
+    translate(:description,
+              scope: [:Authenticate, :controllers, :passwords],
+              default: t('passwords.create.description'))
+  end
+
+  def flash_success_password_changed
+    translate(:success_password_changed,
+              scope: [:Authenticate, :controllers, :passwords],
+              default: t('flashes.success_password_changed'))
+  end
+
+  def flash_failure_token_expired
+    translate(:failure_token_expired,
+              scope: [:Authenticate, :controllers, :passwords],
+              default: t('flashes.failure_token_expired'))
+  end
+
+  def flash_failure_when_forbidden
+    translate(:forbidden,
+              scope: [:Authenticate, :controllers, :passwords],
+              default: t('flashes.failure_when_forbidden'))
+  end
+
+  def flash_failure_after_update
+    translate(:blank_password,
+              scope: [:Authenticate, :controllers, :passwords],
+              default: t('flashes.failure_after_update'))
+  end
+
+  def url_after_create
+    sign_in_url
+  end
+
+  def url_after_update
+    Authenticate.configuration.redirect_url
+  end
+end