You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 33 Next »

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 subject or her institution) transmitted via identity federation protocols (today SAML 2).

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 add personalized services, e.g. storing of search results or documents).
The absence of such authorization data in a response from the issuer (the Identity Provider) of course means that according to the issuer the subject requesting access is not entitled to the resource.

The service provider needs to actually check for those attributes and deny access if the agreed-upon attribute value was not been provided in the response. 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.

Shibboleth IDP Configuration

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

Define/Assign the attribute

First you'll need to decide on what class of subjects/identities/accounts you consider to be covered by the common (see above) library contract terms. If you consider everyone and everything that can authenticate at your IDP to be authorized to resources covered by this arrangement you can unconditionally generate the entitlement in a "static" DataConnector:

Static generation of the entitlement
<resolver:DataConnector id="staticCommonLibTerms" xsi:type="dc:Static">
    <dc:Attribute id="eduPersonEntitlement">
        <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":

Only "member" affiliates are assigned the entitlement
<resolver:AttributeDefinition xsi:type="ad:Mapped" id="MemberCommonLibTerms"
    dependencyOnly="true" sourceAttributeID="eduPersonAffiliation">
    <resolver:Dependency ref="eduPersonAffiliation" />
    <ad:ValueMap>
        <ad:ReturnValue>urn:mace:dir:entitlement:common-lib-terms</ad:ReturnValue>
        <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.:

Add Dependency to eduPersonEntitlement definition
<resolver:AttributeDefinition id="eduPersonEntitlement" xsi:type="ad:Simple">
    <resolver:Dependency ref="myLDAP" />
    <resolver:Dependency ref="MemberCommonLibTerms" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:eduPersonEntitlement" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="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) library service providers by name (i.e., 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.)

Even though we try to keep these rules 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).

Release eduPersonEntitlement by enumerating SPs
<afp:AttributeFilterPolicy id="CommonLibTerms">
    <afp:PolicyRequirementRule xsi:type="basic:OR">
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://test-sp.aco.net/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://ieeexplore.ieee.org/shibboleth-sp" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="http://shibboleth.ebscohost.com" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://dl.acm.org/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://sp.tshhosting.com/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://www.content-select.com/simplesaml/module.php/saml/sp/metadata.php/preselect.media-sp" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://www.emeraldinsight.com/entity" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://www.emeraldinsight.com/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://sdauth.sciencedirect.com/" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://www.tandfonline.com/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://fsso.springer.com" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://shibboleth.genios.de/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://shibboleth.statista.com" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://www.hanser-elibrary.com/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://shibboleth.ovid.com/entity" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://prd.thieme.de/shibboleth-sp" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://elibrary.chbeck.de/Shibboleth.sso" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://elibrary.vahlen.de/Shibboleth.sso" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://www.nomos-elibrary.de/Shibboleth.sso" />
    </afp:PolicyRequirementRule>
    <afp:AttributeRule attributeID="eduPersonEntitlement">
        <afp:PermitValueRule xsi:type="basic:AttributeValueString" value="urn:mace:dir:entitlement:common-lib-terms" />
    </afp:AttributeRule>
</afp:AttributeFilterPolicy>

And another example specific for 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.

Release eduPersonScopedAffiliation by enumerating SPs that don't support entitlements
<afp:AttributeFilterPolicy id="LibrarySPsScopedAffiliation">
    <afp:PolicyRequirementRule xsi:type="basic:OR">
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://shibboleth.cambridge.org/shibboleth-sp" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://shibboleth.highwire.org/entity/secure-sp" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://secure.nature.com/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://secure.palgrave-journals.com/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://sp.onlinelibrary.wiley.com/shibboleth" />
    </afp:PolicyRequirementRule>
    <afp:AttributeRule attributeID="eduPersonScopedAffiliation">
        <afp:PermitValueRule xsi:type="basic:OR">
            <basic:Rule xsi:type="basic:AttributeValueString" value="student" ignoreCase="true" />
            <basic:Rule xsi:type="basic:AttributeValueString" value="staff" ignoreCase="true" />
            <basic:Rule xsi:type="basic:AttributeValueString" value="faculty" ignoreCase="true" />
            <basic:Rule xsi:type="basic:AttributeValueString" value="employee" ignoreCase="true" />
            <basic:Rule xsi:type="basic:AttributeValueString" value="member" ignoreCase="true" />
        </afp:PermitValueRule>
    </afp:AttributeRule>
</afp:AttributeFilterPolicy>

Better approaches

Clearly having a Service Category defined for Library Services would help managing the release policies in a more consistent and less implementation-specific way. Discussion about that is currently ongoing and ACOnet is contributing to further developments in that space. As always, please discuss and share examples with the community.

  • No labels