Protected

Protected is an engine that sits ontop of Devise, which provides common methods for authentication, and user management.

Security Considerations

Protected is specifically designed to support enterprise applications, which often have more stringent security needs than consumer applications. What follows are the extra considerations and precautions we took when designing this engine for use in the enterprise.

Login Validations

  • cannot contain any whitespace

  • cannot contain a period at the start or end

  • must contain at least one letter

  • must contain at least one number

  • must contain at least one these special characters “-_.”

  • can only contain letters number and special characters “-_.”

  • cannot be changed once assigned

Email Validations

  • cannot be changed once assigned

Password Validations

  • must be a minimum of 8 characters

  • is assigned a one-time password upon creation, which must be changed upon the first login

  • to manually reset the password you must know the current password

  • must contain at least one special character “! @ # $ % ^ & + =”

  • must contain at least one lowercase letter [a-z]

  • must contain at least one uppercase letter [A-Z]

  • must contain at least one number [0-9]

Action Audits

Audit logs are created for various actions that users (including admins) undertake. What follows are a list of the actions that create an audit record.

  • a user record is destroyed

  • a user account is unlocked

  • a first name is changed

  • a last name is changed

  • a company name is changed

  • a user has the admin role added or removed from their profile

  • the current and last ip address the user logged in from is recorded

User Flow

  • When resetting a password a user cannot choose any password that matches the previous five they’ve used.

  • When a user fails to log in successfully after five attempts their account is locked.

  • Locked accounts can only be unlocked by user admins

  • User admins cannot view, create or update passwords for the users.

  • There are two roles, a general user and a user admin.

  • Lost passwords can be reset by using a one-time password token sent to the email address associated to the user.

Contributing to Protected

  • Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet.

  • Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it.

  • Fork the project.

  • Start a feature/bugfix branch.

  • Commit and push until you are happy with your contribution.

  • Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Installation

You must use the Rails 3.2 or higher gem with the Protected engine. Add the internal gem repository to your list of gem sources if you have not done so

gem install protected

Create the migration file

rake protected:install:migrations

Create an admin user:

bundle exec rake protected:create_admin

After you install Protected and add it to your Gemfile, you need to run the generator:

rails generate protected:install

The generator will install an initializer and mount an engine to your routes file. You must look at the Protected’s configuration options inside the initializer and ensure everything is configured as you would like it.

To enforce authentication simply call the authenticate_user! method, which you typically use as a before_filter e.g.:

before_filter :authenticate_user!

Customizing Views

If you want to customize the views that protected uses simply run this generator which will add them to your views.

rails g protected:views
Custom Layout for Login / Forgot Password page / Mailer etc

Inside your ‘ configapplication.rb ` use the callback ` to_prepare ` to configure the layout. For example, for configuring a new layout for ` Devise::SessionsController `

config.to_prepare do
  Devise::SessionsController.layout "layout_for_sessions_controller"
  Devise::PasswordsController.layout "layout_for_passwords_controller"
end

Optional Customization

Overriding Routes

By default the routes for Protected are specified in the gem. If you’d like to override any of them here are the routes you’ll need to implement the appropriate routing code in your application’s route file.

devise_for :users, {
    :skip => :all,
    :class_name => 'Protected::User',
    :controllers => { :sessions => 'protected/sessions', 
                      :passwords => "protected/passwords" },
    :module => :devise
}

devise_scope :user do
  get "/sign_in", :to => "sessions#new", :as => "new_session"
  post "sessions", :to => "sessions#create", :as => "user_session"
  get "/sign_out", :to => "sessions#destroy", :as => "destroy_session"
  get 'first_login', :to => 'sessions#first_login', :as => 'first_login'
  put 'update_first_login', :to => 'sessions#update_first_login', :as => 'update_first_login'
  put "/password", :to => "passwords#update", :as => "update_password"
  post "/password", :to => "passwords#create", :as => "create_password"
  get "/password/new", :to => "passwords#new", :as => "new_user_password"
  get "/password/edit", :to => "passwords#edit", :as => "edit_user_password"
  match 'not_authorized', :to => 'sessions#not_authorized'
end

Running Tests

To run tests on this gem extract a local copy and then navigate to the /protected/spec/dummy folder. Then run the following commands:

bundle update rack && bundle install
RAILS_ENV=test rake db:migrate

The navigate to the root of the gem and type:

guard

TODOs

  • Re-enable the password_archiving_count

  • Re-enable the old password archiving.

  • Re-enable deny_old_passwords

  • Re-enable the password_archivable strategy

Maintainers

License

MIT License.