ridaalbarazi.welcome

Here comes the second part of our story, last time in part one we met rails directory structure, designed a three tables database, created it in MySQL and linked it to our application then we let rails db schema create those tables for us and finally we generated a modest scaffold for our Books table.

If you remember last week we added another table in our db schema file which was the Users table, today we will talk about users in our application and how to make our application a more social one.

The options we have in order to have a user management setup for our applications are mainly three:

• Do it ourselves from zero.
• Use some decent plugin like Acts As Authenticated.
• Use a ready generator like Salted Hash Login Generator.

Before we choose between these three let’s see what are the main differences between them:

If we write our code from zero we will definitely learn more, we will have a better understanding of the whole process but at the same time we will be spending too much time on something became very regular and common in every web application and in some way we will be doing some not required extra work.

Acts As Authenticated and Salted Hash Login Generator are almost the same from some functionality point of view but the main difference is that the act is more dynamic and customizable because it is simpler, it let us take care about few things that we should really be responsible of while the generator take care about everything in some more advance way, so personally I prefer to go for Acts As Authenticated for its simplicity and core functionality that will help us understand how things work and allowing us to add some extra functionalities by ourselves.

Acts in rails are some sort of plugins and extensions to our framework extending it with few extra features, there are many great acts we will use in this application, some of them are completely independent from rails and some like Acts As Taggable became so common to the level they got packaged with rails itself.

Acts As Authenticated

It’s a simple system that helps us deal with users in our applications, it generate the required code to support user authentication and management starting from the regular MVC code ending with migration and tests.

Installation

To start with we have first to install the plugin on our system, to do this we have first to update our repositories index and then install the plugin.

D:\\Projects\\Book Swap\\bookswap>ruby script/plugin source http://svn.techno-weenie.net/projects/plugins
Added 1 repositories.

D:\\Projects\\Book Swap\\bookswap>ruby script/plugin install acts_as_authenticated
+ ./acts_as_authenticated/CHANGELOG
+ ./acts_as_authenticated/README
.
.
.
Consult the Acts As Authenticated wiki for more: http://technoweenie.stikipad.com/plugins/show/Acts+as+Authenticated

The Generator

After installing the plugin now we are able to generate all the required files, acts_as_authenticated have mainly two generators, one for the authentication system itself, the core functionalities and their corresponding model, views and controller. And the other generator is the mailer, the one responsible for sending notification and verification emails to our registered users.

To use:

  ./script/generate authenticated user account

This generates a basic user model, a controller, some basic views, and tests.

So to generate the authentication system we have first to decide the controller name to be generated and remember here that the controller is the one that normally appear in our URL (to deal with the books controller we had to call http://localhost:3000/books) so what will be the best controller name for our users? Account? Readers? Owners? Well personally I prefer to stick with the defaults and the classics, at the end these are our applications Users, and this is what we called the database table earlier so let’s stick to it and name it “users”:

D:\\Projects\\Book Swap\\bookswap >ruby script/generate authenticated user users
      exists  app/models/
      exists  app/controllers/
      exists  app/helpers/
      create  app/views/users
      exists  test/functional/
      exists  test/unit/
      create  app/models/user.rb
      create  app/controllers/users_controller.rb
      create  lib/authenticated_system.rb
      create  lib/authenticated_test_helper.rb
      create  test/functional/users_controller_test.rb
      create  app/helpers/users_helper.rb
      create  test/unit/user_test.rb
      create  test/fixtures/users.yml
      create  app/views/users/index.rhtml
      create  app/views/users/login.rhtml
      create  app/views/users/signup.rhtml
      create  db/migrate
      create  db/migrate/001_create_users.rb

If we examine the generated files we can see that acts_as_authenticated has generated for us the user model, users controller and its corresponding views, a helper, some unit and fixture tests and finally a migration file, as we have all these files generated it seems that BookSwap is ready now to have users, let’s see if this is true http://localhost:3000/users

It seems that it works, it already directed us to the signup method http://localhost:3000/users/signup, ok let’s give it a try and see what will happen (click to enlarge):

Oops, we have a problem, but at least we have some information that we can work with to understand what we have done wrong.

Fixing The Conflict

With the user friendly error page we should be able to catch what we’ve done wrong, it’s saying: “undefined local variable or method `crypted_password’ for #<User:0×39499b8>”, so basically the problem is in “crypted_password” and it is in the model User, we remember that the Model is the one that deals with the database, if you remember from our first part in the db schema definition we named the password column “salted_password”:

# This file is autogenerated. Instead of editing this file, please use the
# migrations feature of ActiveRecord to incrementally modify your database, and
# then regenerate this schema definition.
 
ActiveRecord::Schema.define() do
 
  create_table "users" do |t|
    t.column "fullname", :string, :limit => 80
    t.column "login", :string, :limit => 80
    t.column "email", :string, :limit => 60
    t.column "salted_password", :string, :limit => 40
  end
 
  create_table "books" do |t|
    t.column "title", :string
    t.column "author", :string
    t.column "publisher", :string
    t.column "isbn", :string
  end
 
  create_table "users_books" do |t|
    t.column "user_id", :integer, :default => 0
    t.column "book_id", :integer, :default => 0
  end
 
end

So from where did this “crypted_password” come from?

Back to Migrations

Maybe it’s time to go back and check what’s inside the migration file that acts_as_authenticated generated for us and and check if it has anything realted:

class CreateUsers < ActiveRecord::Migration
  def self.up
    create_table "users", :force => true do |t|
      t.column :login,                     :string
      t.column :email,                     :string
      t.column :crypted_password,          :string, :limit => 40
      t.column :salt,                      :string, :limit => 40
      t.column :created_at,                :datetime
      t.column :updated_at,                :datetime
      t.column :remember_token,            :string
      t.column :remember_token_expires_at, :datetime
    end
  end
 
  def self.down
    drop_table "users"
  end
end

First let’s understand the migration process more, the migration is made to allow us move up and down in our application with a decent control over our database modification, in this case we can understand that acts_as_authenticated did create the migration file for us so we migrate to it.

Any migration file is separated into two parts, up and down. From the names “up” is the actions which will take place when we move forward in our migration like migrating from 4 to 5 for example, and “down” will hold the actions that will be executed when we move backward in our migrations like migrating from 6 to 5 for example.

The 001_create_users.rb migration file creates a table in its up method and drop it in its down method, the table it creates is the Users table which we already created earlier in our schema, it almost have all the columns, few more and some with different names, here we can find the mysterious “crypted_password” we saw in the error page, it’s the column we named as “salted_password”, so we found what’s wrong, now how to fix this conflict?

We have to write our own migration instead of using the default migration generated by acts_as_authenticated, we will tweak it to suit our needs. First we don’t need to create the Users table as it is already created, we don’t need to recreate the fields we have already created as well but we need the new fields required by acts_as_authenticated and sure we have to fix and rename the field salted_password into crypted_password. This will make “up” method like this:

  def self.up
    #renaming the previously created column in schema.rb
    rename_column :users, :salted_password, :crypted_password
 
    #adding the new columns required by acts_as_authenticated.
    add_column :users, :salt,                      :string, :limit => 40
    add_column :users, :created_at,                :datetime
    add_column :users, :updated_at,                :datetime
    add_column :users, :remember_token,            :string
    add_column :users, :remember_token_expires_at, :datetime
  end

Instead of the create_table method we used some individual methods that deals with an existing table, add_column, remove_column and rename_column are simple methods that takes the table name as their first parameter and the column name as their second, only the rename_column method takes an extra parameter which is the new column name.

As this is the first migration file we have it got the 001 numbers at the beginning of its name automatically, from now on any new migration will get a serial prefix to its name that indicate its place among other migrations.

Whenever we do any changes or modifications to our database we have to support going back by defining the opposite actions in the “down” method of our migration as follows:

  def self.down
    #renaming the column back.
    rename_column :users, :crypted_password, :salted_password
 
    #removing all the created columns in this migrations.
    remove_column :users, :salt,                      :string, :limin => 40
    remove_column :users, :created_at,                :datetime
    remove_column :users, :updated_at,                :datetime
    remove_column :users, :remember_token,            :string
    remove_column :users, :remember_token_expires_at, :datetime
  end

So at the end our modified 001_create_users.rb file will end up like this:

class CreateUsers < ActiveRecord::Migration
  def self.up
    #renaming the previously created column in schema.rb
    rename_column :users, :salted_password, :crypted_password
 
    #adding the new columns required by acts_as_authenticated.
    add_column :users, :salt,                      :string, :limit => 40
    add_column :users, :created_at,                :datetime
    add_column :users, :updated_at,                :datetime
    add_column :users, :remember_token,            :string
    add_column :users, :remember_token_expires_at, :datetime
  end
 
  def self.down
    #renaming the column back.
    rename_column :users, :crypted_password, :salted_password
 
    #removing all the created columns in this migrations.
    remove_column :users, :salt
    remove_column :users, :created_at
    remove_column :users, :updated_at
    remove_column :users, :remember_token
    remove_column :users, :remember_token_expires_at
  end
end

Logically we have solved the conflict error but there is still one step left which is migrating our application to the latest migration available and for now it is 001, to migrate our application we have to call the command “rake migrate”, if we called it without any parameter it will automatically migrate our database to the latest migration available, if we specified the “VERSION=X“ parameter it will migrate the application to migration X whether it is newer or older from our current migration level.

D:\\Projects\\Book Swap\\bookswap>rake migrate
(in G:/Projects/Book Swap/bookswap)
== CreateUsers: migrating =====================================================
-- rename_column(:users, :salted_password, :crypted_password)
   -> 0.3590s
-- add_column(:users, :salt, :string, {:limit=>40})
   -> 0.3280s
-- add_column(:users, :created_at, :datetime)
   -> 0.3600s
-- add_column(:users, :updated_at, :datetime)
   -> 0.3430s
-- add_column(:users, :remember_token, :string)
   -> 0.3440s
-- add_column(:users, :remember_token_expires_at, :datetime)
   -> 0.3600s
== CreateUsers: migrated (2.0940s) ============================================

Back to our application checking if the user system is working now, let’s try to sign up again and see what we will get (http://localhost:3000/users/signup):

“Train delayed? and what’s to say?” nice poetry after such a cool process, so we are signed up and logged in now, this is what acts_as_authenticated can give us so far and the rest is on us.

Have you noticed that the column fullname didn’t show up in the signup page? That’s because the templates generated by acts_as_authenticated plugin don’t know about it YET.

Tailoring

To be able to tailor and customize the authenticated system we have to understand the generated files and know how to deal with them and we will start with the views:

The generated templates are three, login, signup and index, they are all placed under the “users” subdirectory in our app/views directory, what we want is to allow users to add their fullnames when they signup so let’s have a quick look at the signup.rhtml template:

<%= error_messages_for :user %>
<% form_for :user do |f| -%>
<p><label for="login">Login</label><br/>
<%= f.text_field :login %></p>
 
<p><label for="email">Email</label><br/>
<%= f.text_field :email %></p>
 
<p><label for="password">Password</label><br/>
<%= f.password_field :password %></p>
 
<p><label for="password_confirmation">Confirm Password</label><br/>
<%= f.password_field :password_confirmation %></p>
 
<p><%= submit_tag 'Sign up' %></p>
<% end -%>

It looks that we have a pattern for every property of the user object to generate its corresponding form input, if we followed the same pattern to generate the required input for the user fullname our template will look like this:

<%= error_messages_for :user %>
<% form_for :user do |f| -%>
<p><label for="login">Login</label><br/>
<%= f.text_field :login %></p>
 
<p><label for="email">Email</label><br/>
<%= f.text_field :email %></p>
 
<p><label for="fullname">Full Name</label><br/>
<%= f.text_field :fullname %></p>
 
<p><label for="password">Password</label><br/>
<%= f.password_field :password %></p>
 
<p><label for="password_confirmation">Confirm Password</label><br/>
<%= f.password_field :password_confirmation %></p>
 
<p><%= submit_tag 'Sign up' %></p>
<% end -%>

This template like any other rhtml view template contains two types of code, the basic xhtml/html code and an embedded ruby code which we call ERb. To embed a ruby code in our views we have to surround it with <% and %> this will execute the ruby code but it will not show any output so it’s called “evaluation ERb block”, if we want to show the output of this code we have to add an equal sign after the introductory signs so it will be surrounded by <%= and %> and this is called “output ERb block”.

In any of the ERb block types we will deal mainly with two things, first is the ActionController methods and actions, these will help us generate the required xhtml/html, js and xml code in a dynamic smooth way.

The second thing we will deal with in our views is the instance variable received from the related action in the related controller, each view will be parsed after its corresponding action in its related controller is requested, in that particular action we set some instance variables that we can manipulate in our views, we will see that in more details soon.

How is it working?

In order to understand the code and the way it is generated in signup.rhtml let’s have a look at the parsed version of it, the html source code of the page we get in our browser when we call http://localhost:3000/users/signup:

<form action="/users/signup" method="post"><p><label for="login">Login</label><br/>
<input id="user_login" name="user[login]" size="30" type="text" /></p>
 
<p><label for="email">Email</label><br/>
<input id="user_email" name="user[email]" size="30" type="text" /></p>
 
<p><label for="fullname">Full Name</label><br/>
<input id="user_fullname" name="user[fullname]" size="30" type="text" /></p>
 
<p><label for="password">Password</label><br/>
<input id="user_password" name="user[password]" size="30" type="password" /></p>
 
<p><label for="password_confirmation">Confirm Password</label><br/>
 
<input id="user_password_confirmation" name="user[password_confirmation]" size="30" type="password" /></p>
 
<p><input name="commit" type="submit" value="Sign up" /></p>
</form>

Back to our rhtml template we notice that it starts with an output ERb block with the method error_messages_for which will output all the error messages of the user object in this form if there is any, as we don’t have any errors here we didn’t find any related html code in the parsed version.

Then comes an evaluation ERb block that opens a block by its turn, the form_for method do the required preparation to output a form fully customized to hold the information of a specific object and by ready I mean setting this form inputs names and ids to form a set of the object’s data in the post parameters. So what we do is to specify the object name we are preparing this form for, which in our case “user”, we can also specify the action this form will be directed to when it’s submitted, if we don’t specify any (like in our case) it will be submitted to itself so our form will be submitted back to the signup action of the users controller.

The form_for method prepared a form helper object for the “user” object and name it “f”, then the generating of the required inputs for each column started by simply calling their corresponding helper methods, notice that only two methods are used so far: text_field and password_field and they are called as methods of the form helper object called “f”, notice as well that these methods are called in an output ERb block so they can return their output in the parsed template.

Let me try to simplify this code by trying to write it in plain English: “Start a form for a new user then generate the required text fields and password fields for this user and then post them back to the same current page.”

The main idea of setting the names and ids of the generated inputs is to simplify the way we deal with them in our actions as post parameters, rails has a standard for this and therefore it has the ready tools to generate what’s required to follow these standards and get things faster.

After we are done with our form fields we find a submit_tag named “Sign up” then the form_for block is simply closed by an “end” and we are done. When someone signup and fill all these fields and hit the sign up button the form data will be posted to the same action “signup” where it will be handled to add a new user to the Users table accordingly, if it faced any errors it will return to the same form and show the errors at the top (as the results of the error_messages_for method), if not it will simply login to our poetry page.

Are We Logged In?

Now let’s change this literal poetry in the index.rhtml template to some code poetry, how about we change the output of this view depending on the status of the user, if he/she is logged in we show a link to logout, if not we show links to either signup or to login. I don’t think this is difficult it’s just a quick if statement:

<% if logged_in? %>
You are logged in, you can now <%= link_to "log out", :action => 'logout' %>
<% else %>
You are not logged in please either <%= link_to "login", :action => 'login' %> or <%= link_to "signup", :action => 'signup' %>
<% end %>

I guess the code is self-explanatory now, I just want to note that we used the method logged_in?, in ruby whenever there is a method with a question mark “?” at the end of it will return a Boolean, True or False, so in English it’s like a simple question, is the current user logged in? this method is a part of the acts_as_authenticated plugin.

The other thing I wanted to talk about here is the link_to method, it is an ActionView helper method, it generates an anchor, takes the first parameter as the anchor name and the second as the action name we want to link to, it will automatically understand and generate the corresponding URL of the action we specify, for example when we specify the “logout” action it will know automatically that its URL is http://localhost:3000/users/logout.

So we have changed our index.rhtml file, now let’s see if it’s working and how it will look like, remember that our last state where logged in after we signed up and saw the lovely poetry:

We are logged in, that’s true, it seems that everything is really working fine and we don’t have any problems so far, how about the link to “logout”? is it working? let’s check out:

Yes it is working, we are logged out now and we have one of two options, either to login again or to signup for a new account, try logging in and out again to see how it’s working and then let’s try a new signup to see if the fullname field we have added is present or not:

Wonderful, we have a simple user authentication system now that we modified a little, so far it works for signup, login and logout, it doesn’t do anything more yet but at least it helped us understand few concepts and how things work at the backend.

More Security by Filtering

To care more about security and to get the most benefit out of the latest rails 1.1.6 security release let’s use the new method of ActionController (released in rails 1.1.6) “filter_parameter_logging”:

“ActionController#filter_parameter_logging lets you filter form data that you don’t want saved in the log. This is useful for preventing sensitive data like passwords and credit card numbers from being logged in the clear, for keeping huge pieces of data from clogging the log file, and so on.” from Filtered Parameter Logging of the Ruby on Rails official Blog.

This method job –as clarified in rails weblog- is to filter fields from being logged, in our case what we want to filter is the password fields and we will do that by adding the filter_parameter_logging line to our application controller in controllers/application.rb:

# Filters added to this controller will be run for all controllers in the application.
# Likewise, all the methods added will be available for all controllers.
class ApplicationController < ActionController::Base
  filter_parameter_logging :password
end

By doing this the password and password_confirmation fields will never be logged anymore and will be replaced by “[FILTERED]” in the log files, to check that yourself you can check your log/development.log file and see how the passwords of the users added to the system earlier were plainly logged while the passwords of any new users will be replaced with “[FILTERED]“.

Summary

In this part we have implemented the Acts As Authenticated plugin into our application, modified it a little and understood few backend behaviors specifically the way the view templates handle ERb code, we also had a better look at Migrations and understood how they help us have a better control over our database modifications in a very dynamic way.

During the next week I will release a sidenote post on how to checkout the project files from the subversion repository I’m using for it, I’m also working on creating packaged files for each part of the tutorial and will release it on RubyForge soon too.

In the next part we will talk about relationships, as for now we have a user system and a simple books system, we will link them together using some magic relationship mapping from ActiveRecord maybe we will do some testing as well to ensure things are working properly, so… see you next week.