CSCI E-168

Errata

(15-Nov-2009) Apparently the gem dependencies have changed for Clearance; you will also need to install the factory_girl gem. I’ve noted this below, so if you’re following only the screencast, make sure to see Step 3 below.

This is the first of two screencasts on using Clearance for authentication. The first screencast
presents the basics of getting Clearance to work with a new application; in the second screencast,
we’ll go over retro-fitting an existing application. The screencast link is at the bottom: I’d recommend that you read or skim the screencast steps before viewing.

1. Let’s check your gem configuration.

   On Windows, or on Linux or OS/X and using ruby_switcher.sh, you do not need to run gem as the superuser. If you installed Ruby by hand on Linux or OS/X, you will need to prefix the gem command with “sudo”, for example “sudo gem install foobar”, not “gem install foobar”.

   First let’s make sure that your gem sources are all up to date. Type

   gem sources
   

   If http://gems.github.com is not listed, do

   gem source -a http://gems.github.com
   

   There is also a new gem source, which will supersede RubyForge. Do the
   following:

   gem install gemcutter
   gem tumble
   

   This will make gemcutter the top priority for gems. It has everything
   from RubyForge.

2. To get a feel for how a new gem works, I would advise trying it out in
   “scratch” application that you intend to throw away. So first go into a
   temporary directory. Also, we’ll create a scaffold for a single table,
   just so we have something there that the application can manipulate.

   rails scratch
   cd scratch
   mv public/index.html public/index.html_orig
   script/generate scaffold Note title:string description:string
   rake db:migrate
   

   If you like, you can now do script/server, browse to http://localhost:3000/notes
   and create some sample data.

3. Now let’s install the clearance gem. There are some brief install
   instructions here — http://github.com/thoughtbot/clearance — and you can
   also preview the code. (15-Nov-2009: You will also need the factory_girl gem.)

   gem install thoughtbot-clearance
   gem install thoughtbot-factory_girl
   

4. We would like to have our application require a specific version. To do that:

   In config/environment.rb

   config.gem "thoughtbot-clearance",
     :lib     => 'clearance',
     :source  => 'http://gems.github.com',
     :version => '0.8.2'
   

5. Note that you can use rake to ensure that all gems specific through config
   are installed; and you can also “unpack” them into your own application so that
   if you need to deploy to an environment that doesn’t have the gem, your app
   will still work.

   rake gems:install
   rake gems:unpack GEM=thoughtbot-clearance
   

   (rake gems:unpack will unpack ALL gems you’ve specified: Here, we’re just
   going to do it for clearance.)

6. Generate clearance

   script/generate clearance
   

7. FIRST, make sure you don’t lose track of the directions printed out
   after generating clearance. We want to go back to that. Before we go
   further, however, we should see what has happened to your application.
   Notice that right after the script/generate command, the generator tells
   us what files were added or modified:

   insert  include Clearance::Authentication into app/controllers/application_controller.rb
   exists  app/models
   create  app/models/user.rb
   create  test/factories
   create  test/factories/clearance.rb
   exists  db/migrate
   create  db/migrate/20091101174550_clearance_create_users.rb
   readme  README
   

   As you can see, the generator make some significant changes. We need to
   take a look at app/controllers/application_controller.rb, the User model that
   was created, and the migration.

   For application_controller.rb, we see that the module Clearance::Authentication
   has been included. This means that we are going to have access to some new
   methods in our application controller, and all controllers that subclass it.

   The created User model is quite simple:

   # Remember: Generated code: Don't add this yourself!
   class User < ActiveRecord::Base
     include Clearance::User
   end
   

   Finally, the migration is pretty significant:

   # Remember: Generated code: Don't add this yourself!
   class ClearanceCreateUsers < ActiveRecord::Migration
     def self.up
       create_table(:users) do |t|
         t.string   :email
         t.string   :encrypted_password, :limit => 128
         t.string   :salt,               :limit => 128
         t.string   :confirmation_token, :limit => 128
         t.string   :remember_token,     :limit => 128
         t.boolean  :email_confirmed, :default => false, :null => false
         t.timestamps
       end
   
       add_index :users, [:id, :confirmation_token]
       add_index :users, :email
       add_index :users, :remember_token
     end
   
     def self.down
       drop_table :users
     end
   end
   

   This last bit is important. It means that if we add clearance to an application
   that already has a users table and a User model, we will have to modify the
   migration so that it is not creating a users table, but adding columns.

8. Follow the instructions given after script/generate:
   

   1. Define a HOST constant in your environments files.
   In config/environments/test.rb and config/environments/development.rb it can be:

   HOST = “localhost”

   In production.rb it must be the actual host your application is deployed to.
   The constant is used by mailers to generate URLs in emails.

   2. In config/environment.rb:

   DO_NOT_REPLY = “donotreply@example.com”

   3. Define root_url to *something* in your config/routes.rb:

   map.root :controller => ‘home’

   So, in our case, we’ll set HOST to localhost:3000, and the map.root to
   the “notes” controller.

9. Migrate the database

   rake db:migrate
   

10. Now you might think that clearance is working. Browse to http://localhost:3000/notes

    Nothing. The docs don’t tell you what to do. If you get caught in
    this situation, your best bet is to try to find the Clearance::Authentication
    module, and see if there are any interesting methods on it. You might
    also look at the tests.

    So, let’s look at vendor/gems/thoughtbot-clearance-0.8.2/lib/clearance/authentication.rb

    AHA! A method called authenticate. Now, we probably want this to run
    before any actions on protected resources.

    Notice as well that there is also an action called sign_out

11. Now add to any controller that needs authentication . . .

    before_filter :authenticate
    

    An alternative is to create a controller that auth-protected controllers
    should subclass:

    class RequiresAuthenticationController < ApplicationController
      before_filter :authenticate
    end
    

12. Try it. Browse back to http://localhost:3000/notes
13. Ah. We’re being forced to log in. Let’s register. We’re sent back to
    login. Now, most authentication systems require you to click an authentication
    link; clearance is no different. Let’s check the log. And there it is. Let’s
    grab that link and paste it in.
14. It works. We’re authenticated.
15. The route for logout is . . . /sign_out, i.e., http://localhost:3000/sign_out
16. At this point, we might add sign_in and sign_out links to our scaffold
    layout.

Click for screencast