Auth Module (Developer Notes)
The Auth module extends functionality available from the [Authlogic|http://github.com/binarylogic/authlogic] (version 2.1.0) gem and included in the lib directory based on the [Authlogic OpenID add-on|http://github.com/binarylogic/authlogic_openid].'
The idea is to allow services to be customized based on user attributes. Some examples could be:
- Store a user's mobile phone number or email address to default the txt/email values for those services.
- Provide extended request or paging functionality that is only available to a subset of patrons.
- Allow faculty members to place items on reserve from the Umlaut screen.
Umlaut Files Added or Updated
Several core Umlaut files were added and updated in order to support the Auth module.
The ApplicationController filters passwords and provides two methods for accessing the current user session and the current user.
- current_user_session (aliased as has_logged_in_user) - returns nil if no user session has been established
- current_user (aliased as logged_in_user) - returns either nil or the current logged in user
The application calls current_user_session as a before filter on every request.
The UserSessionsController manages the routing of user session requests and provides three methods.
- new - renders the login screen or redirects to external login screen
- validate - validates the user upon login
- destroy - processes logout
The UsersController manages the routing of user related requests and provides two methods.
- edit (also called from show) - renders the user preferences screen
- update - processes updates to user preferences (not yet implemented)
UserSessions extends Authlogic::Session::Base
User serializes user_attributes and adds acts_as_authentic functionality to leverage the Authlogic gem. Also sets to_param to username rather than id for prettier urls.
The default login screen, doesn't currently do anything.
The default user preferences screen. Users can update mobile phone numbers and the like (not yet implemented)
Added authlogic gem:
#require 'authlogic' config.gem 'authlogic', :version => "= 2.1.0"
Added url routes:
map.login "login", :controller => "user_sessions", :action => "new" map.logout "logout", :controller => "user_sessions", :action => "destroy" map.validate "validate", :controller => "user_sessions", :action => "validate" map.resources :user_sessions map.resources :users
Modified the user table to use with authlogic. Included column for mobile phone, user attributes and a refreshed_at date to track age of a particular record for better performance.
Make the user accessible from a particular user via the session_user method.
# Returns the currently logged in user, if available, based on the user_credentials_id in the # session from AuthLogic. May want to make this more sophisticated and check user_credentials # against db. def session_user return User.find(session["user_credentials_id"]) unless session["user_credentials_id"].nil? end
The following files makeup the Auth module to extend the functionality of Authlogic for our purposes.
The ActsAsAuthentic module extends the authlogic user model to ignore passwords, reset_persistence_token when the username changes, manage stale data (via refreshed_at date), and handle user attributes hash.
The Session module establishes the Auth module callback functions and can serve as a template for further localizations. Callback functions to be overridden locally as appropriate:
- before_login - called when a new user session is being established, before the actual login is called
- login_url - called if before_login isn't defined or returns false, convenience method for redirecting to an external login url
- after_login - called after login user has been validated, provides mechanism for authorization
- before_logout - called before current user session is destroyed
- after_logout - called after current user session is destroyed
- on_every_request - called on every request
The module also has two private methods for use in extended local classes.
- validate_url - generates the return url to send to external logins services
- session_user - facilitates saving user attributes to the user model
Configuring Local Auth Modules
Auth Module Example
AuthPDS was developed at NYU as an example of generating a plugin and populating the stub methods provided.
The AuthPDS module gets mixed in with the Session module to log in via PDS (customized for NYU). It implements the following callback functions:
- login_url - provides PDS login URL to redirect to
- after_login - checks authorization, stores some cookies to improve performance, saves some user data when appropriate
- logout_url - provides PDS logout URL
- after_logout - destroys some cookies that were stored to improve performance
- on_every_request - checks if the user has logged in (e.g. from another SSO system)
The auth configuration settings are added to the local environment.rb to establish the appropriate class to mix in and to pass various options to the module.