These instructions assume you have an authentication system and therefore a user model and some way of logging in/out of your system.

Lockdown strives to be as easy to implement into an existing system as it is when starting from scratch. This is why Lockdown has few integration points in your application code.

In an existing application, just run:

stonean$ ./script/generate lockdown
      exists  app/views
      exists  app/controllers
      exists  app/helpers
      create  lib/lockdown
      create  lib/lockdown/README
      create  lib/lockdown/init.rb
      exists  app/models
      create  app/models/user_group.rb
      create  app/models/permission.rb
      exists  db/migrate
      create  db/migrate/004_create_user_groups.rb
      exists  db/migrate
      create  db/migrate/005_create_permissions.rb
      create  config/initializers/lockit.rb

As you can see from the above output, very few files are place in your system.

For simplicity sake and no other real reason, we’ll just go in order they are generated and give a brief description.

README

First is the README file (as seen below). This gives you a brief summary of what we are going to cover here in the wiki.

#
#                           !!!!IMPORTANT!!!!
#
#*** MUST define a current_user method that will return the current user object
#
#*** MUST add call to add_lockdown_session_values to your login method
#
#*** MAY NEED to add call to reset_lockdown_session to your logout method. 
# ** Not needed if your authentication system resets the session
#   
# Definitely need to use the user_group and permission models.  The lockdown 
# generator will provide those for you.  Just add the following to your user
# model:
#   has_and_belongs_to_many :user_groups
#
# That's it! 
#
#
#                       ~~~~Method Descriptions~~~~

# The Lockdown gem defines these session methods:
#
# current_user_id: returns the id of the current_user
#
# logged_in? : returns true if current_user_id > 0
#
# current_user_is_admin?: returns true if user is assigned 
# administrator rights.
#
# reset_lockdown_session: This will nil the following session values:
#   current_user_id
#   access_rights
#   expiry_time
#
# current_user_access_in_group?(grp):  grp is a symbol referencing a 
# Lockdown::UserGroups method such as :registered_users
# Will return true if the session[:access_rights] contain at 
# least one match to the access_right list associated to the group
#
# If you want access to any of these methods in your view, just add them 
# as helpers in your controller (application controller for global use).

init.rb

This is the configuration file for Lockdown. Here you will define your permissions and user groups. A sample can be found here.

the models

The generator will create the user_group and permission models along with their migrations. Unless you want some specific functionality you won’t need to modify these files.

Making it work

Believe it or not you’re almost done. As the README states, there are only a few things required:

• MUST define a current_user method that will return the current user object
  • This is a pretty standard way of doing things so it may be done already.
• MUST add call to add_lockdown_session_values to your login method
  • This method adds the information to the session Lockdown needs to operate.
• If your logout method does not reset_session, you need to add a call to :reset_lockdown_session in your logout method.
  • This will clear the lockdown specific values from the session.
• Add

  has_and_belongs_to_many :user_groups

  to your user model.
  • Lockdown will expect user.user_groups to be available, so this is a requirement.

Once things things are done, your system is now locked down. This isn’t a play on words, you really won’t be able to access ANYTHING until you define public access in init.rb.

IMPORTANT

One of the things that trip people up the most is dealing with public permissions. As you are developing your application, you will be changing public access. At some point you’ll make a change to public_access and it won’t work. This is because the state of your last configuration is still defined in your session. Call the logout method (which should be calling :reset_lockdown_session) to reset your session. Do this even if you weren’t logged in to begin with.

I am working on a way to automatically detect init.rb changes to eliminate this issue. There are simple solutions, but I need to make sure it works in a load balanced setup, which complicates things.

Well, that’s about it. Please let me know if anything here was missing or vague and I’ll update the docs. I would like them to be easy to follow and as complete as possible.