Library Services

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 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 (the Identity Provider) of course means that according to the issuer the subject requesting access is not entitled to the resource. Consequently Attribute Based Access Control (ABAC) means 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.

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

(Due to some fallout after a website reconstruction at Internet2 the defintion of the common-lib-terms Entitlement value is currently inaccessible. Thankfully archive.org has an older copy of that specificiation. Please see that for the semantics of that attribute.)

The NameFormat (what format is the the formal attribute name in) is always "urn:oasis:names:tc:SAML:2.0:attrname-format:uri". For legacy protocol versions (SAML1.x) the formal attribute name is "urn:mace:dir:attribute-def:eduPersonEntitlement" instead. See https://eduid.at/entities/sp and "mouse-over" the attribute name to find out its required formal name.

Shibboleth 2.4 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).

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:

<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":

<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 used by adding a Dependency to the existing AttributeDefinition for eduPersonEntitlement (make sure to uncomment the defintion first), on either "staticCommonLibTerms" or "MemberCommonLibTerms" (but not both), e.g.:

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

TBC (Next up: adjusting the attribute filter to release the attribute).