SAML Authentication

HathiTrust has implemented authentication using the Security Assertion Markup Language (SAML), a mechanism for federated authentication, in order to allow specialized services for persons affiliated with member institutions. Authentication via a SAML identity provider (IdP) is required for authentication to HathiTrust. HathiTrust uses the Shibboleth Service Provider (SP) software, but can interoperate with any SAML-compliant identity provider such as Shibboleth, CAS, OpenAthens, Microsoft ADFS, SimpleSAMLphp, etc. Current services offered to authenticated individuals affiliated with member institutions include:

• full-PDF download of public domain works
• facilitated access to the Collection Builder application, which makes it possible for users to aggregate works into permanent collections either for private use or to share publicly with others
• special access for users who have a print disability (only in the U.S.; see https://www.hathitrust.org/accessibility)

To receive these services, HathiTrust member institutions must meet the following requirements:

• belong to a SAML federation for which HathiTrust is a registered service provider; currently, InCommon (for partners in the US) with inter-federation supported via eduGAIN for national federations in other countries such as CAF (in Canada), AAF (in Australia), SIR (in Spain), the UK Access Management Federation, etc. We are also a registered service provider with OpenAthens. For members in other countries, please contact us and we will work with you to register with the appropriate federation.
• enable communication with the HathiTrust service provider (SP) through the release of certain attributes (see below for details)
• have updated contact information in their federation metadata; in some cases HathiTrust metadata contact requirements go beyond what the federation requires (e.g. for InCommon members HathiTrust requires support and technical contacts, while federation guidelines are more relaxed).

We will work directly with members to ensure that the SAML authentication connection is tested and working properly.

The entityID for the HathiTrust Service Provider is http://www.hathitrust.org/shibboleth-sp. Our metadata is available in InCommon and is interfederated via eduGAIN. It is also available directly via the InCommon Metadata Query service. Further details about HathiTrust SAML authentication follow below. Please contact support@hathitrust.org with any questions, or to test your SAML authentication configuration.

Terms and Conditions

The Collection Builder, full-PDF download, and enhanced access services provided through SAML authentication are made available to faculty, staff, students, and alumni at participating HathiTrust institutions.

SAML attributes that must be released to HathiTrust to provide services

• eduPersonScopedAffiliation (required) – to verify a user’s affiliation with their source institution
  • The scope asserted (represented as institution.edu below) must match a scope present in the identity provider metadata.
  • To facilitate download of public domain books: We accept the values 'member@institution.edu' and/or 'alum@institution.edu'
  • To faciliate access to the Emergency Temporary Access Service: We accept the values 'student@institution.edu,' 'staff@institution.edu', and/or 'faculty@institution.edu'.
  • Note: we have worked with some campuses to accept alternative values for this attribute. Contact us at feedback@issues.hathitrust.org if you have questions about how your campus is configured in our systems. 
• SAML2 persistent NameID (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) OR eduPersonTargetedID (preferred) OR eduPersonPrincipalName (acceptable) – to identify a specific user for purposes of collection building and access to material with limited numbers of concurrent users
  
  • If an institution does not yet have support for persistent NameID or eduPersonTargetedID, we will accept eduPersonPrincipalName with the understanding that if a user's eduPersonPrincipalName were to change, their saved personalized HT environment would no longer be available to them.
• displayName (desired) – to identify creators of publicly curated collections
  
  • If an institution doesn't wish to release displayName, we will use the eduPersonPrincipalName if provided. If neither are provided, the creators of publicly-curated collections will be anonymous.
• eduPersonEntitlement (optional) – to identify additional users eligible for library privileges
• We accept the urn:mace:dir:entitlement:common-lib-terms value for eduPersonEntitlement to identify users with regular library privileges at their home institution who are not considered "members" by their institution. Some examples could include doctoral candidates not enrolled in classes ("ABD" students), visiting scholars, sponsored instructors, etc. This entitlement provides regular member privileges. It does not provide access to material via ETAS; that is limited to users considered active faculty, staff, and students by their home institution.
• We may in the future provide additional direct services for users with print disabilities via the eduPersonEntitlement attribute. (current services for users who have print disabilities is offered via an institutional Proxy - see https://www.hathitrust.org/accessibility). Some preliminary values of the attribute that have been discussed are as follows:
  • https://www.hathitrust.org/access/enhancedText - attribute value for users who have a print disability
  • http://www.hathitrust.org/access/enhancedTextProxy - attribute value for those accessing works on behalf of users who have a print disability
  • https://www.hathitrust.org/access/standard - attribute value for standard use. This attribute value is not required but is provided for Identity Providers that prefer to enter an entitlement value for all users.
• library-walk-in (optional) – eduPersonScopedAffiliation value which may be supported in the future to offer certain member services to guest users (for instance, full-PDF download of all public domain materials or access to works that are brittle, missing, and also out of print). The library-walk-in attribute will not enable personalized services, such as the ability to save volumes to permanent personal collections. Members who wish to use HathiTrust library-walk-in functionality must confirm in writing that they are asserting the library-walk-in affiliation only for users physically present in a library building at the time of session initiation.\

Multi-Factor Authentication

Some HathiTrust services, such as the Accessible Text Request Service, can use multi-factor authentication (MFA) to verify a users' identity. This uses the SAML authnContextClassRef element to indicate the authentication method used to sign on to HathiTrust. HathiTrust can accept the standard REFEDS MFA profile. This is the same configuration used by other service providers including the US National Institutes of Health electronic Records Administration (NIH eRA), so if you are able to pass the NIH sign-in test then your identity provider configuration should meet HathiTrust requirements as well. InCommon provides a guide for implementing these requirements.

Privacy

The eduPersonPrincipalName and displayName attributes, which convey personally identifiable information, are desired and will be used to identify the creators of public curated collections on HathiTrust web pages. The contents of eduPersonPrincipalName, displayName and eduPersonEntitlement, if provided to HathiTrust, will be used solely for the delivery services and will not be distributed to third parties or saved in databases other than those that function to deliver HathiTrust services. The eduPersonScopedAffiliation, SAML2 persistent name ID, and eduPersonTargetedID attributes do not provide personally-identifying information. Identity providers may release other attributes to HathiTrust which are not used by the application but may be retained in authentication logs.

Note on Proxy Servers

HathiTrust does not support access via proxy servers like EZProxy that attempt to provide IP-based access to authenticated users. We do not recommend using proxy servers with HathiTrust for the following reasons:

• Users do not gain additional access to materials when coming from campus IP addresses.
• HathiTrust uses rate-limiting to ensure compliance with third-party agreements and provide a consistent user experience for all users. Our rate-limiting mechanisms treat all users accessing through a proxy server as a single user, so the more users that access from a proxy server at a given institution, the more likely those users are to have their rate of access limited.
• Using a proxy server may impede an institution's ability to ensure compliance with restrictions on use of HathiTrust materials, possibly granting unintended access for users who are not faculty, students or staff, or facilitating other unauthorized access.
• Access through proxy servers is slower, more complex, and prone to breakage.

 Last updated November 3, 2020