[DRAFT] [DRAFT] [DRAFT] [DRAFT]
Is this document for ME?
It is if you are a staff member at an academic institution (that uses EZProxy) who wishes to begin implementing Shibboleth access to library resources, but are unsure about what is required and what is involved.
Why this document?
By laying out the necessary pre-requisites as well as the steps involved, the hope is that this document will enable the reader to decide IF moving to Shibbolized access to library resources is feasible at his/her institution, and if it is, will provide a "cookbook" for the process.
What are the pre-requisites for integrating Shibboleth and EZproxy?
- An institution-wide (enterprise) directory service that contains information about the users for whom you wish to authorize access to electronic resources.
- An Identity management environment (policies and business practices) that governs the management of identity information for the users in the enterprise directory. This is necessary to build and maintain the trust necessary to participate in a federation such as InCommon.
- A Shibboleth IdP from which service providers (EZproxy itself, JSTOR, OCLC, Elsevier, etc) can obtain sufficient identity information about each user of their services who requests access.
- An EZproxy installation that provides authenticated remote access to library resources.
- Institutional membership in a federation such as InCommon
What are the steps?
Step 1: Configure Identity Provider (IdP) to release standard entitlement attributes (eduPersonEntitlement)
The Best Practice document, https://spaces.at.internet2.edu/display/inclibrary/Best+Practices
, for the InCommon Federation details the standard entitlement attribute that has been agreed upon in the InCommon Federation to enable authorization for standard library licensed resources. In brief, the standard entitlement attribute is eduPersonEntitlement, and the standard entitlement for representing the terms of common library contracts is 'urn:mace:dir:entitlement:common-lib-terms'. More details as to the reason for this particular attribute are available in the Best Practices.
In order for resource providers to make authorizations based on this entitlement attribute according to the Best Practices, the institution's identity provider must be configured to release this attribute. This step must be performed by the administrator of the institution's identity provider. The identity provider is typically not administered by the library, rather, it is usually maintained by the central IT office for the institution.
The Shibboleth identity provider can be configured with policies to release user attributes to different resource providers. These policies are referred to as attribute release policies (ARPs). The attribute release policy is the mechanism by which the IdP administrator will release the eduPersonEntitlement attribute with the common-lib-terms value. In order for the IdP administrator to configure the attribute release policy to release this attribute properly, they must know two pieces of information: 1) what users should this attribute be released for, and 2) what resource providers should this attribute be released to.
1) What users should this attribute be released for - The common-lib-terms entitlement value was established to represent the members of an institution that are included in the terms of typical library contract with a library resource provider. The interpretation may vary slightly at each institution, but this typically includes students, faculty, staff and people physically present in the library. The common-lib-terms value is registered with MACE and documented here: http://middleware.internet2.edu/urn-mace/urn-mace-dir-entitlement.html.
The administrator of the identity provider will need to use some logic based on available user attributes from the enterprise directory, to determine what users are covered under the common-lib-terms entitlement. The library and the identity provider administrator will need to work together to interpret common-lib-terms entitlement and the logic that is needed to implement it.
2) What resource providers should this attribute be released to - As this is an attribute that is agreed to as a Best Practice for the InCommon community, this entitlement attribute *can* be released to all resource providers in the InCommon Federation. IdP administrators may choose though to release this selectively to resource providers. If the latter is the case, the entitlement attribute will need to be released to each resource provider that the institution enables Shibboleth access to, as well as the library's EZproxy installation (to be discussed in next step).