Gem Version Build Status Dependency Status Code Climate Coverage Status


Libraries for authenticating via Ex Libris' Patron Directory Services (PDS) and provides hooks for making authorization decisions based on the user information provided by PDS. It leverages the authlogic gem and depends on a User-like model.


Generate User-like model

$ rails generate model User username:string email:string firstname:string \
  lastname:string mobile_phone:string crypted_password:string password_salt:string \
  session_id:string persistence_token:string login_count:integer last_request_at:string \
  current_login_at:string last_login_at:string last_login_ip:string current_login_ip:string \
  user_attributes:text refreshed_at:datetime

Configure User-like model

class User < ActiveRecord::Base
  serialize :user_attributes  

  acts_as_authentic do |c|
    c.validations_scope = :username
    c.validate_password_field = false
    c.require_password_confirmation = false  
    c.disable_perishable_token_maintenance = true

Generate UserSession model

$ rails generate authlogic:session user_session

Configure UserSession with Authpds options

class UserSession < Authlogic::Session::Base
  pds_url ""
  redirect_logout_url ""
  calling_system "my_system"

  def expiration_date

Create UserSessions controller

$ rails generate controller UserSessions --no-assets --no-helper

Configure institutions

Create institutions.yml file

Calling the institution "default" will make it the default:

    code: INST01
  display_name: My Institution

An alternative syntax:

    code: INST01
  default: true
  display_name: My Institution

You can create multiple institution listings as follows:

    code: INST01
  default: true
  display_name: My Institution
    code: INST01
  display_name: Your Institution

The two separate institutions above share a code in this example. The code attribute determines the institute parameter in the PDS url.

Institution fields

Field Description
name Institution name
display_name Name to display to users.
default Boolean indicating whether this is a default Institution. Alternatively, an Institution can be named 'default'.
parent_institution A parent Institution from which this child will inherit fields.
ip_addresses IP addresses associated with the Institution.
login Login configurations associated with the Institution.
layouts Layout configurations associated with the Institution.
views View configurations associated with the Institution.
controllers Controller configurations associated with the Institution.
models Model configurations associated with the Institution.

Create institution initializer

Most likely it will just work if you put the config file in


If you have your institutions config file in another location make sure to change the line below accordingly.

Institutions.loadpaths << File.join("other", "path")
Institutions.filenames << "other_file.yml"

Mixin authpds methods into UserSessionsController

class UserSessionsController < ApplicationController
  require 'authpds'
  include Authpds::Controllers::AuthpdsSessionsController

Mixin authpds methods into ApplicationController

class ApplicationController < ActionController::Base
  require 'authpds'
  include Authpds::Controllers::AuthpdsController

Mixin institution url helpers into ApplicationHelper

module ApplicationHelper
  include Authpds::Helpers::Institution::UrlHelper


The Authpds gem mixes in callbacks to Authlogic for persisting sessions based on a valid PDS handle. The module extends Authlogic and should be compatible with Authlogic configuation. It also provides hooks for custom functionality. The documentation below describes the hooks available for overriding, PDS config methods and further details about the module.

Config Accessors Available

Accessor Description
#pds_url Base pds url
#calling_system Name of the system (authpds)
#anonymous Does the system allow anonymous access? (true)
#pds_attributes Mapping of PDS attributes to record attributes
#redirect_logout_url Custom redirect logout url
#login_inaccessible_url Custom url to redirect to in case of PDS system outage
#pds_record_identifier PDS user method to call to identify record
#institution_param_key Querystring parameter key for the institution value in this system
#validate_url_name URL name for validation action in routes (validate_url)

Hooks Available for Overriding

Hook Description
#pds_record_identifier Allows for more complex logic in determining what should be used as the record identifier. Defaults to what was set in the pds_record_identifier config. Returns a Symbol.
#attempt_sso? If there is no PDS handle, can we attempt to establish a PDS session based on some other information? Returns a Boolean.
#additional_authorization Allows for additions to the authorization decision. Returns a Boolean.
#additional_attributes Allows for additional attributes to be stored in the record. Returns a Hash.
#expiration_date Indicates when the record information should be refreshed. Defaults to one week ago. Returns a Date or Time.

Further Implementation Details

Persisting a Session in AuthLogic

When persisting a Session, Authlogic attempts to create the Session based on information available without having to perform an actual login by calling the #persisting? method. Authologic provides several callbacks from the #persisting? method, e.g. #before_persisting, #persist, #after_persisting. We're using the #persist callback and setting it to #persist_session.

Access to the controller in Session

The class that Session extends, Authologic::Session::Base, has an explicit handle to the current controller via the instance method #controller. This gives our custom instance methods access to cookies, session information, loggers, etc. and also allows them to perform redirects and renders.