Versions Compared

Old Version 15

changes.mady.by.user Peter Brand

Saved on

compared with

New Version Current

changes.mady.by.user Peter Brand

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: update syntax for IDPv5

Library services, databases and academic content providers still use IP addresses (and often IPv4 only) for mapping "users" (network addresses, really) to contracts. There is little we can do today to change this other than to engage with every publisher on the planet to request and help them with integrating identity federation technology. All content providers are encouraged to (and in many cases already do) base authorization of individuals accessing their resources on attributes (i.e., data about the user subject or her institution) transmitted via identity federation protocols (today SAML 2.0+).

In most cases the only information required by a content provider will be an attribute detailing whether an individual is covered by an existing contract. (Sometimes an identifier unique to the subject will also be required and will allow the service provider to also add personalized services, e.g. storing of search results or documents).
The absence of such authorization data in a response from the issuer (i.e., the Identity Provider) of course means that according to the issuer the subject requesting access is not entitled to access the resource. Consequently Attribute Based Access Control (ABAC) means the

Note
iconfalse

The service provider needs to actually check for those attributes and deny access if the agreed-upon attribute value

...

has not been provided in the response.

...

Note
iconfalse

There is no other way for an institution to signal whether an individual should be entitled to a resource or not. Authentication at an academic institution does not mean the subject is necessarily authorized to access licensed resources on behalf of that institution.

The eduPerson specification has defined the generic attribute eduPersonEntitlement to communicate entitlements, permissions or rights between entities. For the specific case of library services MACE-Dir has then defined a standard eduPersonEntitlement attribute value (see below for details). This is the only attribute (other than maybe a unique identifier) library services will generally need, as such no more data should be sent from the Identity Provider:

common-lib-terms Entitlement

Here's the current common-lib-terms specification.

"Friendly" attribute nameFormal SAML2 attribute name (on-the-wire)Attribute value string
eduPersonEntitlementurn:oid:1.3.6.1.4.1.5923.1.1.1.7urn:mace:dir:entitlement:common-lib-terms

The NameFormat (what format is the formal attribute name in) is always "urn:oasis:names:tc:SAML:2.0:attrname-format:uri". For legacy services still using the SAML1.x protocol the formal attribute name is "urn:mace:dir:attribute-def:eduPersonEntitlement" (instead of urn:oid:1. 3.6.1.4.1.5923.1.1.1.7). See https://eduid.at/entities/sp and "mouse-over" the requested attribute's name to find out its formal name for a given service, if in doubt.

...

To add support for this SAML attribute to your Shibboleth IDP 3.x you'll need to adapt the configuration files attribute-resolver.xml (to generate the attribute) and attribute-filter.xml (to release the attribute).

Define

...

the attribute

...

See our IDP 4 Attribute resolution documentation for a simple example of how to generate and assign the common-lib-terms entitlement based on eduPersonAffiliation values.

Release the attribute

The most explicit way of releasing this attribute (value) is by listing all relevant (to you) library service providers by name, i.e., referencing their entityID. See https://eduid.at/entities/sp (or https://eduid.at/entities/sp/interfed for Interfederation particpants) for a current list of Service Providers, their entityID and Requested Attributes. (For SPs known via Interfederation any Requested Attributes are managed and accounted for by their respective Home Federation, not by ACOnet. Also note that not all uses of eduPersonEntitlement you'll encouter are specific to this attribute value, i.e., specific to library services.)

Note

Even though we try to keep the rules on this page up-to-date and fully functional, they are meant as examples that will likely also include services your institution does not have a contract/subscription with (or might be missing ones you do). No problems should result from including more services here than you have access to, though, as these services require contracts (and usually payment) in order to provide access, so sending the right SAML attributes is a necessary pre-condition but not sufficient alone.


Code Block
languagehtml/xml
titleStatic generation of the entitlementRelease eduPersonEntitlement by enumerating SPs
<AttributeFilterPolicy<resolver:DataConnector id="staticCommonLibTerms"CommonLibTerms">
    <PolicyRequirementRule xsi:type="dc:StaticOR">
    <dc:Attribute id="eduPersonEntitlement"    <Rule xsi:type="Requester" value="https://test-sp.aco.net/shibboleth" />
        <dc:Value>urn:mace:dir:entitlement:common-lib-terms</dc:Value>
    </dc:Attribute>
</resolver:DataConnector>

Alternatively, in the probably more common case of only a part of your population being entitled, you can assign the entitlement to only those identified as being sufficiently authorized by another attribute, e.g. an eduPersonAffiliation value of "member":

Code Block
languagehtml/xml
titleOnly "member" affiliates are assigned the entitlement
<resolver:AttributeDefinition<Rule xsi:type="Requester" value="https://ieeexplore.ieee.org/shibboleth-sp" />
        <Rule xsi:type="ad:MappedRequester" idvalue="MemberCommonLibTerms"http://shibboleth.ebscohost.com" />
    dependencyOnly="true" sourceAttributeID="eduPersonAffiliation">
   <Rule <resolver:Dependency ref="eduPersonAffiliationxsi:type="Requester" value="https://sp.tshhosting.com/shibboleth" />
    <ad:ValueMap>
      <Rule  <ad:ReturnValue>urn:mace:dir:entitlement:common-lib-terms</ad:ReturnValue>xsi:type="Requester" value="https://www.content-select.com/simplesaml/module.php/saml/sp/metadata.php/preselect.media-sp" />
        <ad:SourceValue>member</ad:SourceValue>
    </ad:ValueMap>
</resolver:AttributeDefinition>

One of the two attribute definitions will then be referenced as a Dependency in the existing AttributeDefinition for eduPersonEntitlement (make sure to uncomment the definition first), on either "staticCommonLibTerms" or "MemberCommonLibTerms" (but not both), e.g.:

Code Block
languagehtml/xml
titleAdd Dependency to eduPersonEntitlement definition
<resolver:AttributeDefinition id="eduPersonEntitlement" xsi:type="ad:Simple"<Rule xsi:type="Requester" value="https://sdauth.sciencedirect.com/" />
    <resolver:Dependency ref="myLDAP" />
   <Rule <resolver:Dependency ref="MemberCommonLibTermsxsi:type="Requester" value="https://www.tandfonline.com/shibboleth" />
        <resolver:AttributeEncoder<Rule xsi:type="enc:SAML1StringRequester" namevalue="urn:mace:dir:attribute-def:eduPersonEntitlementhttps://fsso.springer.com" />
       <resolver:AttributeEncoder <Rule xsi:type="enc:SAML2StringRequester" namevalue="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" friendlyName="eduPersonEntitlement" />
</resolver:AttributeDefinition>

Release the attribute

The most explicit way of releasing this attribute (value) is by listing all relevant (to you) Service Providers by name. See https://eduid.at/entities/sp (or https://eduid.at/entities/sp/interfed for Interfederation particpants) for a current list of Service Providers, their entityID and Requested Attributes. (For SPs known via Interfederation any Requested Attributes are managed and accounted for by their respective Home Federation, not by ACOnet/eduID.at. Also note that not all uses of eduPersonEntitlement you'll encouter are specific to this attribute value, i.e., specific for library services.)

Code Block
languagehtml/xml
titleRelease eduPersonEntitlement by enumerating SPs
<afp:AttributeFilterPolicy id="CommonLibTerms">
    <afp:PolicyRequirementRule xsi:type="basic:OR">https://secure.nature.com/shibboleth" />
        <Rule xsi:type="Requester" value="https://shibboleth.genios.de/shibboleth" />
        <Rule xsi:type="Requester" value="https://shibboleth-faz.genios.de/shibboleth" /> 
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://test-spshibboleth.acostatista.net/shibbolethcom" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://ieeexplorewww.ieeehanser-elibrary.orgcom/shibboleth-sp" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="httphttps://shibboleth.ebscohostovid.com/entity" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://dlprd.acmthieme.org/oa/metadatade/shibboleth-sp" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://spwww.tshhostingbeck-elibrary.comde/shibbolethShibboleth.sso" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://www.contentnomos-selectelibrary.comde/simplesaml/module.php/saml/sp/metadata.php/preselect.media-spShibboleth.sso" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://wwwiam.content-selectatypon.net/simplesaml/module.php/saml/sp/metadata.php/preselect.media-spcom/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://wwwportal.emeraldinsightzedhia.comat/entitysaml" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://sdauthsp.sciencedirecteblib.com/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://www.tandfonlinelogin.intelliconnect.inta.cch.com/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://fssoshibbolethsp.springerjstor.comorg/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://shibboleth-sp.geniosprod.proquest.decom/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://shibbolethelibrary.statistaverlagoesterreich.comat" />
    </afp:PolicyRequirementRule>
    <afp:AttributeRule<AttributeRule attributeID="eduPersonEntitlement">
        <afp:PermitValueRule<PermitValueRule xsi:type="basic:AttributeValueStringValue" value="urn:mace:dir:entitlement:common-lib-terms" />
    </afp:AttributeRule>
</afp:AttributeFilterPolicy>

...

And another example specific to those library SPs that do not support the standard "common-lib-terms" entitlement and instead rely on eduPersonScopedAffiliation values. What affiliation values (student, faculty, staff, member, etc.) should be entitled to access licensed resources in each case cannot be known a priori – usually each institution's librarians need to decide and can configure authorized affiliation values in a self-service web interface provided by the publisher/e-resource provider. If in doubt ask the service provider and/or discuss with the eduID.at community.

Note

We'd prefer the number of library services using eduPerson(Scoped)Affiliation to be zero, since using the "common-lib-terms" eduPersonEntitlement is advantageous for eveyone involved: the SP, the IDP and the federation operator (or federation operators, globally). So the services listed below are where we (as an academic community) failed to communicate those benefits cleary and consistently (or it just fell on deaf ears) – with the exception of a handful of SPs that treat different populations differently and therefore require affiliation attributes.


Code Block
languagehtml/xml
titleRelease eduPersonEntitlement by relying on RequestedAttribute in SAML MetadataeduPersonScopedAffiliation by enumerating SPs that don't support entitlements
<AttributeFilterPolicy<afp:AttributeFilterPolicy id="ACOnetSPsCommonLibTermsLibrarySPsScopedAffiliation">
    <PolicyRequirementRule <afp:PolicyRequirementRulexsi:type="OR">
        <Rule xsi:type="saml:AttributeRequesterInEntityGroup" groupID="http://eduid.at/md/aconet-registered.xml"Requester" value="https://shibboleth.cambridge.org/shibboleth-sp" />
        <Rule xsi:type="Requester" value="https://shibboleth.highwire.org/entity/secure-sp" />
        <Rule xsi:type="Requester" value="https://ticket.iop.org/shibboleth" />
        <Rule <afp:AttributeRule attributeID="eduPersonEntitlement"xsi:type="Requester" value="https://shib.rsc.org/shibboleth" />
        <afp:PermitValueRule<Rule xsi:type="basic:AND""Requester" value="https://sp.emerald.com/sp" />
        <Rule xsi:type="Requester" value="https://cas.manz.at/shibboleth"  <basic:Rule/>
        <Rule xsi:type="saml:AttributeInMetadataRequester" onlyIfRequiredvalue="truehttps://lindedigital.at/shibboleth" />
        <Rule xsi:type="Requester" value="https://shib.lexisnexis.com" />
        <basic:Rule<Rule xsi:type="basic:AttributeValueStringRequester" value="urn:mace:dir:entitlement:common-lib-termshttps://signin.lexisnexis.com/lnaccess/fed/authn" />
        <Rule xsi:type="Requester" value="https://www.utb-studi-e-book.de/websso/metadata" />
        </afp:PermitValueRule>
    </afp:AttributeRule>
</afp:AttributeFilterPolicy>

IDPs also participating in Interfederation will need to adjust the value of groupID in the PolicyRequirementRule to "http://eduid.at/md/aconet-interfed.xml", to accomodate for a different Name of the eduID.at Interfederation-enabled metadata aggregate. Note that for SPs not registered by ACOnet, only known via Interfederation agreements, it is not ACOnet who checks the appropriateness of Requested Attributes in SAML metadata, but the registering ("home") federation. If in doubt, check the other federations' Registration Practice Statements (e.g. for eduGAIN member federations).

More scalable approaches

<Rule xsi:type="Requester" value="https://elibrary.hogrefe.de" />
        <Rule xsi:type="Requester" value="https://sp.ebrary.com/shibboleth" />
    </PolicyRequirementRule>
    <AttributeRule attributeID="eduPersonScopedAffiliation">
        <PermitValueRule xsi:type="OR">
            <Rule xsi:type="Value" value="student"  caseSensitive="false" />
            <Rule xsi:type="Value" value="staff"    caseSensitive="false" />
            <Rule xsi:type="Value" value="faculty"  caseSensitive="false" />
            <Rule xsi:type="Value" value="employee" caseSensitive="false" />
            <Rule xsi:type="Value" value="member"   caseSensitive="false" />
            <Rule xsi:type="Value" value="library-walk-in" caseSensitive="false" />
        </PermitValueRule>
    </AttributeRule>
</AttributeFilterPolicy>

Better approaches

Having Clearly having a Service Category defined for Library Services would might help managing the release policies in a more consistent and less implementation-specific way. Discussion about that is currently ongoing and ACOnet is awaiting (and contributing to) and proposals for that sometimes appear and ACOnet is actively contributing to further developments in that space. If no progress can be made internationally ACOnet might define a cartegory locally, if welcomed or requested by the community. Please discuss As always, please discuss and share examples with the community.