Page History

...

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 (i.e., the Identity Provider) of course means that according to the issuer the subject requesting access is not entitled to access the resource.

Note

icon	false

The service provider needs to actually check for those attributes and deny access if the agreed-upon attribute value was has 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 name	Formal SAML2 attribute name (on-the-wire)	Attribute value string
eduPersonEntitlement	`urn:oid:1.3.6.1.4.1.5923.1.1.1.7`	`urn: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

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:

Code Block

language	html/xml
title	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":

Code Block

language	html/xml
title	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.:

Code Block

language	html/xml
title	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>

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 these 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

language	html/xml
title	Release eduPersonEntitlement by enumerating SPs

<afp:AttributeFilterPolicy<AttributeFilterPolicy id="CommonLibTerms">
    <afp:PolicyRequirementRule<PolicyRequirementRule xsi:type="basic:OR">
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://test-sp.aco.net/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://ieeexplore.ieee.org/shibboleth-sp" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="http://shibboleth.ebscohost.com" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterString" value="https://dl.acm.org/shibboleth" />
        <basic:Rule xsi:type="basic:AttributeRequesterString"Requester" value="https://sp.tshhosting.com/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://www.content-select.com/simplesaml/module.php/saml/sp/metadata.php/preselect.media-sp" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://wwwsdauth.emeraldinsightsciencedirect.com/entity" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://www.emeraldinsighttandfonline.com/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://sdauthfsso.sciencedirectspringer.com/" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://wwwsecure.tandfonlinenature.com/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://fssoshibboleth.springergenios.comde/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://shibboleth-faz.genios.de/shibboleth" /> 
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://shibboleth.statista.com" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://www.hanser-elibrary.com/shibboleth" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://shibboleth.ovid.com/entity" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://prd.thieme.de/shibboleth-sp" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://www.beck-elibrary.chbeck.de/Shibboleth.sso" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://www.nomos-elibrary.vahlen.de/Shibboleth.sso" />
        <Rule  <basic:Rulexsi:type="Requester" value="https://iam.atypon.com/shibboleth" />
        <Rule xsi:type="Requester" value="https://portal.zedhia.at/saml" />
        <Rule xsi:type="Requester" value="https://sp.eblib.com/shibboleth" />
        <Rule xsi:type="basic:AttributeRequesterString"Requester" value="https://login.intelliconnect.inta.cch.com/" />
        <Rule xsi:type="Requester" value="https://www.nomos-elibrary.de/Shibboleth.ssoshibbolethsp.jstor.org/shibboleth" />
        <Rule xsi:type="Requester" value="https://shibboleth-sp.prod.proquest.com/shibboleth" />
        <Rule xsi:type="Requester" value="https://elibrary.verlagoesterreich.at" />
    </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 for 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

language	html/xml
title	Release eduPersonScopedAffiliation by enumerating SPs that don't support entitlements

<afp:AttributeFilterPolicy<AttributeFilterPolicy id="LibrarySPsScopedAffiliation">
    <afp:PolicyRequirementRule<PolicyRequirementRule xsi:type="basic:OR">
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://shibboleth.cambridge.org/shibboleth-sp" />
        <basic:Rule<Rule xsi:type="basic:AttributeRequesterStringRequester" value="https://shibboleth.highwire.org/entity/secure-sp" />
        <basic:Rule <Rule xsi:type="Requester" value="https://ticket.iop.org/shibboleth" />
        <Rule xsi:type="Requester" value="basic:AttributeRequesterString"https://shib.rsc.org/shibboleth" />
        <Rule xsi:type="Requester" value="https://securesp.natureemerald.com/sp" />
        <Rule xsi:type="Requester" value="https://cas.manz.at/shibboleth" />
        <basic:Rule<Rule xsi:type="Requester" value="https://lindedigital.at/shibboleth" />
        <Rule xsi:type="basic:AttributeRequesterString"Requester" value="https://shib.lexisnexis.com" />
        <Rule xsi:type="Requester" value="https://securesignin.palgrave-journalslexisnexis.com/lnaccess/shibbolethfed/authn" />
        <basic:Rule <Rule xsi:type="Requester" value="https://www.utb-studi-e-book.de/websso/metadata" />
        <Rule xsi:type="basic:AttributeRequesterString"Requester" value="https://elibrary.hogrefe.de" />
        <Rule xsi:type="Requester" value="https://sp.onlinelibrary.wileyebrary.com/shibboleth" />
     </afp:PolicyRequirementRule>
    <afp:AttributeRule<AttributeRule attributeID="eduPersonScopedAffiliation">
        <afp:PermitValueRule<PermitValueRule xsi:type="basic:OR">
            <basic:Rule<Rule xsi:type="basic:AttributeValueStringValue" value="student"  ignoreCase="true" />
            <basic:Rule<Rule xsi:type="basic:AttributeValueStringValue" value="staff"    ignoreCase="true" />
            <basic:Rule<Rule xsi:type="basic:AttributeValueStringValue" value="faculty"  ignoreCase="true" />
            <basic:Rule<Rule xsi:type="basic:AttributeValueStringValue" value="employee" ignoreCase="true" />
            <Rule <basic:Rulexsi:type="Value" value="member"   ignoreCase="true" />
            <Rule xsi:type="basic:AttributeValueStringValue" value="memberlibrary-walk-in" ignoreCase="true" />
        </afp:PermitValueRule>
    </afp:AttributeRule>
</afp:AttributeFilterPolicy>

Better approaches

Clearly having 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 and proposals for that sometimes appear and ACOnet is actively contributing to further developments in that space. As always, please discuss and share examples with the community.

ACOnet Identity Federation

Content

Page tree

Versions Compared

Old Version 33

New Version Current

Key

common-lib-terms Entitlement

Define

the attribute

Release the attribute

Better approaches

Links

Help

Intranet Tools