Tech Blog

PDS OpenSSO Integration

  • Description
NYU has integrated PDS with Sun’s OpenSSO Identity Management application. The PDS/OpenSSO integration uses PDS as the NYU Libraries’ single sign-on system and leverages NYU’s OpenSSO system to provide seamless interaction between library applications and university services. The integration merges patron information from OpenSSO (e.g. name, email, e-resources access) with patron information from Aleph (e.g. borrower status and type) to ensure access to the multitude of library services.
The NYU Libraries operate in a consortial environment in which not all users are in OpenSSO and not all OpenSSO users are in Aleph. PDS is hosted in an active/passive capacity on our Primo front-end servers. Due to the nature of PDS and Aleph, patrons are required to have an Aleph account in order to login to the library’s SSO environment. The exception to this rule is EZProxy.
  • Author: Scot Dalton
  • Institution: New York University
  • Year: 2009
  • License: BSD style
  • Short description: Use, modification and distribution of the code are permitted provided the copyright notice, list of conditions and disclaimer appear in all related material.
  • Skill required for using this code: Advanced

State

Production

Programming language

Perl, CSS, HTML

Software requirements

OpenSSO

Screen captures

NYU Look and Feel

Generic Look and Feel

 

Author(s) homepage

http://library.nyu.edu

Download

Version 2.1

Working example

https://pds.library.nyu.edu:443/pds?func=load-login&institute=NYU

Using the following Ex Libris open interfaces

PDS and Aleph X-Services

Release notes

In this release we’ve improved performance through a variety of methods:
  1. Exported patrons into a flat file that is stored on disk to improve performance. The file is rebuilt every three hours. If a patron is not in the flat file, Aleph is checked via an X-Service call.
  2. Z311 and Z312 files are written directly from the script rather than redirecting which save an http redirect. Generally we’ve tried to minimize the number of http redirects in order to streamline the process of establishing a session.
We’ve also cleaned up the code, so maintenance is easier. We’ve abstracted out the Patron model to enable more straightforward processing of the Aleph patrons.

Workflow

Scenario 1: Signed into OpenSSO before PDS

  1. LOAD_SSO directive in tab_service.nyu instructs PDS to use opensso.pl passing in the opensso.conf configuration and “passive” login flag
  2. opensso.pl::opensso – PDS checks OpenSSO through Net::OpenSSO::check_authentication
  3. opensso.pl::opensso – If an OpenSSO session exists, continue, otherwise go to calling system as guest
  4. opensso.pl::opensso – Get the OpenSSO user from Net::OpenSSO::get_user
  5. opensso.pl::opensso – Check authorization which means seeing if the user is in Aleph
  6. opensso.pl::check_authorization – Get N number via OpenSSO user attribute nyuidn
  7. opensso.pl::check_authorization – Check for Aleph patron through NYU::Libraries::Aleph::Patron::exists
  8. NYU::Libraries::Aleph::Patron::exists – Check if the patron is in the flat file. If not, check if the patron exists in the bor_by_key x-service
  9. opensso.pl::opensso – If patron authorized (e.g. exists in Aleph), continue, otherwise go to calling system as guest
  10. opensso.pl::opensso – Write basic information in z311 file
  11. opensso.pl::opensso – Write OpenSSO information in z312 file
  12. opensso.pl::opensso – Session created, go to system.
  13. BOR_INFO directive in tab_service.nyu instructs PDS to aleph_flat_n_extended.pl passing in the opensso.conf configuration
  14. aleph_flat_n_extended.pl::aleph_flat_n_extended.pl – Get patron
  15. aleph_flat_n_extended.pl::patron – Get patron from NYU::Libraries::Aleph::Patron::get
  16. NYU::Libraries::Aleph::Patron::get – Get patron from flat file if exist, if not get from bor_info x-service
  17. aleph_flat_n_extended.pl::patron – Merge Aleph patron info with OpenSSO info store in z312 file
  18. aleph_flat_n_extended.pl::aleph_flat_n_extended.pl – Send XML string with combined borrower info.

Scenario 2: Sign into PDS

  1. PDS login screen logs into OpenSSO and then calls func=load_login on return from OpenSSO
  2. LOAD_LOGIN directive in tab_service.nyu instructs PDS to use opensso.pl passing in the opensso.conf configuration and “active” login flag
  3. opensso.pl::opensso – PDS checks OpenSSO through Net::OpenSSO::check_authentication
  4. opensso.pl::opensso – If an OpenSSO session exists, continue, otherwise log and display error since something went wrong with OpenSSO
  5. opensso.pl::opensso – Get the OpenSSO user from Net::OpenSSO::get_user
  6. opensso.pl::opensso – Check authorization which means seeing if the user is in Aleph
  7. opensso.pl::check_authorization – Get N number via OpenSSO user attribute nyuidn
  8. opensso.pl::check_authorization – Check for Aleph patron through NYU::Libraries::Aleph::Patron::exists
  9. NYU::Libraries::Aleph::Patron::exists – Check if the patron is in the flat file. If not, check if the patron exists in the bor_by_key x-service
  10. opensso.pl::opensso – If patron authorized (e.g. exists in Aleph), continue, otherwise log and display error since patron is not authorized
  11. opensso.pl::opensso – Write basic information in z311 file
  12. opensso.pl::opensso – Write OpenSSO information in z312 file
  13. opensso.pl::opensso – Session created, go to system.
  14. BOR_INFO directive in tab_service.nyu instructs PDS to aleph_flat_n_extended.pl passing in the opensso.conf configuration
  15. aleph_flat_n_extended.pl::aleph_flat_n_extended.pl – Get patron
  16. aleph_flat_n_extended.pl::patron – Get patron from NYU::Libraries::Aleph::Patron::get
  17. NYU::Libraries::Aleph::Patron::get – Get patron from flat file if exist, if not get from bor_info x-service
  18. aleph_flat_n_extended.pl::patron – Merge Aleph patron info with OpenSSO info store in z312 file
  19. aleph_flat_n_extended.pl::aleph_flat_n_extended.pl – Send XML string with combined borrower info.

Upgrade Process

  1. Add the Class::Accessor perl module via cpan: cd /exlibris/product/perl-5.8.8/bin; ./perl -MCPAN -e ‘install Class::Accessor’
  2. Update customized files and add custom directory for NYU perl modules
  3. In directory /exlibris/primo/p1_1/primoe/apache/htdocs, symbolically link /exlibris/primo/p1_1/pds/html_form/local/ to serve out local css files.
  4. sudo /exlibris/primo/p1_1/primoe/apache/bin/apachectl restart

Environment

PDS is active/passive load balanced on the Primo front-end servers. (c1 and c3 in dev; t1 and t3 in prod).
PDS root directory is /exlibris/primo/p1_1/pds

Aleph Password Encryption

In order to ensure NYU patrons with NetIDs log in with their NetIDs, Aleph passwords have been encrypted using MD5 encryption with a shared secret between PDS and the PLIF loader.

Customized Files

ExLibris PDS Files

Core PDS Files

  • program/PDSLogout.pm:
    • pass url parameter for redirecting.
  • program/PDSParamUtil.pm
    • updated to passback OpenSSO goto URL, to enable EZProxy functionality
ExLibris HTML Files
  • html_form/calling_system-aleph/remote-and-local-list: this file handles scenarios where Aleph is the calling system and no institute is passed in. Look and feel customized for NYU.
  • html_form/global/remote-and-local-list: this file handles scenarios where either the calling system is not separated out by PDS (Primo) or a calling system was not specified in the request and no institute is passed in. Look and feel customized for NYU.
  • html_form/global/redirect-logout: this file handles redirects specified by the REDIRECT_LOGOUT directive in tab_service.* files. Customized for NYU to include a url query string parameter passed in from program/PDSLogout.pm.

ExLibris Config Files

  • /exlibris/primo/p1_1/primoe/apache/conf/httpd.conf:
        # NYU Specific Location
        <Location /logout>
          SetHandler perl-script
          PerlResponseHandler ModPerl::Registry
          Options +ExecCGI
          PerlOptions +ParseHeaders
          PerlSendHeader On
          Allow from all
        </Location>
    
        ScriptAlias "/logout" "/exlibris/primo/p1_1/pds/program/logout.pl" added for custom destruction of NYU Library SSO cookies
    
  • /exlibris/primo/p1_1/primoe/apache/conf/ssl.conf:
        # BEGIN NYU PATRON SCRUBBING
        RewriteEngine On
        RewriteCond %{HTTP_REFERER} ^.*func=remote-sso* [OR]
        RewriteCond %{QUERY_STRING} ^.*func=remote-sso*
        RewriteRule .* - [env=dontlog:yes,QSA]
        ErrorLog "| /exlibris/primo/p1_1/product/local/apache/bin/rotatelogs -l /exlibris/primo/p1_1/primoe/apache/logs/error_log_ssl.%Y-%m-%d 86400"
        CustomLog "| /exlibris/primo/p1_1/product/local/apache/bin/rotatelogs -l /exlibris/primo/p1_1/primoe/apache/logs/access_log_ssl.%Y-%m-%d 86400" special env=!dontlog
        # END NYU PATRON SCRUBBING
    
  • conf_table/general_conf: customized to set DEFAULT_INSTITUTE of NYU for Metalib, Primo, Aleph, Umlaut and Xerxes in order to enable Single Sign On.
  • conf_table/sso_conf: customized to set DEFAULT_INSTITUTE of NYU for Metalib, Primo, Aleph, Umlaut and Xerxes in order to enable Single Sign On.
  • conf_table/heading-error.eng: customized to handle SSO error text in accordance to the PDS standard.

NYU Local PDS Files

Perl Modules

  • custom/Net/OpenSSO.pm
  • custom/NYU/Libraries/Aleph/Patron.pm
  • custom/NYU/Libraries/XService/Common/XBase.pm
  • custom/NYU/Libraries/XService/Aleph/XAlephBase.pm
  • custom/NYU/Libraries/XService/Aleph/XBorInfo.pm
  • custom/NYU/Libraries/XService/Aleph/XBorByKey.pm

HTML Files

  • html_form/institute-bob/login: handles the scenario when the institute passed in the query string is BOB. Generic look and feel and customized for OpenSSO
  • html_form/institute-cu/login: handles the scenario when the institute passed in the query string is CU. Customized for Cooper Union look and feel and OpenSSO
  • html_form/institute-ns/login: handles the scenario when the institute passed in the query string is NS. Customized for New School look and feel and OpenSSO
  • html_form/institute-nysid/login: handles the scenario when the institute passed in the query string is NYSID. Customized for NYSID look and feel and OpenSSO
  • html_form/institute-nyu/login: handles the scenario when the institute passed in the query string is NYU. Customized for NYU look and feel and OpenSSO
  • html_form/institute-nyu/logout: deletes cookies set by library applications for session management

CSS Files

  • html_form/local: local directory was created to handle local css. Symbolic link to directory was create in /exlibris/primo/p1_1/primoe/apache/htdocs for serving out the local css files.
  • html_form/local/bob.css: customized css file for generic login screen
  • html_form/local/common.css: common css file for login screens
  • html_form/local/cu.css: customized css file for Cooper Union login screen
  • html_form/local/ns.css: customized css file for New School login screen
  • html_form/local/nysid.css: customized css file for NYSID login screen
  • html_form/local/nyu.css: customized css file for NYU login screen

Perl Scripts

  • program/logout.pl: custom cgi script to destroy cookies set by other NYU Libraries and Ex Libris applications for SSO
  • service_proc/opensso_sso.pl: custom script to broker login via OpenSSO
  • service_proc/aleph_flat_n_extended.pl: custom script to provide borrower information from a combination of OpenSSO and Aleph, using the flat file provided by the DBA.

Config Files

  • conf_table/tab_service.bob: specifies services associated with the generic BobCat institution.
  • conf_table/tab_service.cu: specifies services associated with the CU PDS institution.
  • conf_table/tab_service.ns: specifies services associated with the NS PDS institution.
  • conf_table/tab_service.nysid: specifies services associated with the NYSID PDS institution.
  • conf_table/tab_service.nyu: specifies services associated with the NYU PDS institution.
  • conf_table/BOB.tags: Mapping of Aleph borrower statuses to Primo institutions for the generic BobCat PDS institution.
  • conf_table/CU.tags: Mapping of Aleph borrower statuses to Primo institutions for the CU PDS institution.
  • conf_table/NS.tags: Mapping of Aleph borrower statuses to Primo institutions for the NS PDS institution.
  • conf_table/NYSID.tags: Mapping of Aleph borrower statuses to Primo institutions for the NYSID PDS institution.
  • conf_table/NYU.tags: Mapping of Aleph borrower statuses to Primo institutions for the NYU PDS institution.
  • conf_table/opensso.conf: All configuration related to the OpenSSO integration.

TO DO List

PLIF on the fly to load OpenSSO users into Aleph based on OpenSSO flags

Known issues

  1. SSO call on initial load into Primo is not working properly.

Comments

We’ve integrated the following systems into the PDS/SSO environment:
ILLiad, Umlaut, Xerxes, EZProxy, Primo and Aleph. EZProxy code is distributed with this code and is based on the CodeShare contribution from Ere Maijala.

Cookies

3 cookies play a part in session management
  • primo: JSESSIONID (if exists, doesn’t immediately call pds LOAD_SSO)
  • opensso: iPlanetDirectoryPro (for now, pds checks this cookie name dynamically)
  • pds: PDS_HANDLE (created by pds after login [guest in some cases])
  • nyu libraries: nyulibrary_opensso_validtoken (created by other NYU applications after login for performance reasons)

Relevant logs

  • /exlibris/primo/p1_1/log/pds_server.log – log for PDS perl modules and perl scripts
  • /exlibris/primo/p1_1/primoe/apache/logs/error_log – logs STDERR for mod_perl and apache errors. useful for looking at OpenSSO perl module.
  • /exlibris/primo/p1_1/primoe/apache/logs/error_log_ssl.<DATE> – logs ssl related errors (not very useful)
  • /exlibris/primo/p1_1/primoe/apache/logs/access_log_ssl.<DATE> – logs pds access requests

Page attachments

pds-nyu-2.1.tar.gz

 

Leave a Reply