200
edits
Changes
no edit summary
[[Category:Umlaut]]
=WARNING: This is Outdated Documentation!!!!=
'''THIS IS OUTDATED DOCUMENTATION''' See new Umlaut documentation at http://github.com/team-umlaut/umlaut/wiki
---------
== 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 a logged in user's 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. Currently the Auth module requires existing Umlaut users to install the authlogic gem and perform a rails migration to update the user model to work with authlogic and the auth module. After these two steps have been taken, the auth module should only take effect if a particular instance has defined a auth module in their local config.
=== Core Umlaut Files Added or Updated ===Several core Umlaut files were added and updated in order to develop support the Auth module.
==== app/controller/application.rb ====
The '''ApplicationController''' filters passwords and provides two methods for accessing the current user session and the current user.
</pre>
==== db/schema.rb ====
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. By default, data expires after 1 week.
==== lib/service.rb ====
Make the user accessible from a particular user via the session_user method.
The following files makeup the Auth module to extend the functionality of Authlogic for our purposes.
==== lib/auth/acts_as_authentic.rb ====
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.
==== lib/auth/session.rb ====
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
# '''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.
At NYU we're currently using the Auth module in our holdings table to offer request functionality based on "patron status". We display a request button, if the patron has the appropriate status to be able to request/page items and use a custom controller to provide this functionality seamlessly. Screenshots of this functionality can be seen below.
==== lib/auth/local/auth_pds.rb ====
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 PDS SSO system)
==== config/umlaut_config/environment.rb ====
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.
<pre>
config.app_config.login = {
# File name
:id => "auth_pds",
# Class name
:module => :AuthPDS,
:options => {
# Make expiration date configurable
:expiration_date => lambda {return 1.week.ago},
# OpenSSO URL, specific to NYU's implementation of PDS.
# Could easily be removed to make the local PDS module more generic.
:opensso_path => "https://login.nyu.edu:443/sso",
# PDS URL
:pds_url => "https://pds.library.institution.edu:443/",
# System name since the module is used in many different contexts and different apps
:system_name => :umlaut,
# Cookie name that is used to help with performance since the module is used in
# many different contexts and different apps
:cookie_name => :nyulibrary_opensso_umlaut,
:additional_user_attributes => lambda do |user_session|
h = {}
# NYU is using this module for several of our ruby apps
# and this mechanism allows us to include different user attributes per system.
# It's included here to give an idea of the flexibility of the module.
return h
end
}
}
</pre>
==== Screenshots of Request Functionality ====
===== Not logged in, no request =====
No request button because generally patrons can't request available items.
== Generating Local UmlautAuth Plugins ==The following steps will generate a stub module for populating for local Auth needs (assumes authlogic version 2.1.0 is installed and user table is up to date).# script/generate UmlautAuth YourModuleName# put your code = Logged in the generated stub methods in vendor/plugins/your_module_name/lib/your_module_name.rb, request =====# add Now the following request button appears because I have permission to config/umlaut_config/environmentrequest available items.rb:<pre>config.app_config.login_modules = [{[Image:id => "your_module_name", :module => :YourModuleName, :default => true }Umlaut_request.png]] #default => true doesn't do anything yet</pre>
=== UmlautAuth Plugin Example == Pretty jQuery modal dialog =====UmlautAuthOpenSSO was developed at NYU as an example of generating a plugin and populating You get the stub methods provided.modal dialog upon clicking the request button* /vendor/plugins/umlaut_auth_open_sso[[Image:Umlaut_request_modal.png]]
