Notes for Attribute Usage
These notes refer to the table on the Attribute Usage page.
1. The only attribute that an identity provider must release for its users to be able to access many services that are licensed for use by everyone at a particular organisation is eduPersonScopedAffiliation. This is a scoped attribute, which might, for example, have the value "member" in scope "uni.ac.uk", often written as:
It is used for the basic authorisation decision: does uni.ac.uk subscribe to the service in question? If so, the user is allowed access. The service provider will maintain its own list of which organisations (scopes) can access its service. For allowed organisations, the federation's Technical Recommendations for Participants indicate that, in HE/FE, users with scoped affilitation values from the set {member, student, staff, faculty, employee} are typically authorised to access content licensed on the basis of the JISC Model Licence, while {affiliate, alum} are not.
An identity provider can generate eduPersonScopedAffiliation automatically (without an attribute store) by setting the required scope in resolver.xml, as described in SetupIdP.
2. Many services can make use of, but do not require, the eduPersonTargetedID attribute. This is a persistent opaque identifier, which enables service personalisation (remembering data about a user over different login sessions) without the service provider knowing who the user is. If the identity provider supplies the eduPersonTargetedID attribute, the session is treated similarly to an Athens personal account. Otherwise, the service's personalisation features (e.g., saved searches) may be disabled, though the service will still function in the same way as with Athens shared accounts. With some services (e.g., Zetoc Alert) this attribute is mandatory. If so, it is marked as "Required/Yes" in the table above.
A Shibboleth identity provider can generate the opaque eduPersonTargetedID attribute automatically from some other stored attribute that holds the user id in the clear, such as eduPersonPrincipalName, by editing resolver.xml and uncommenting or adding:
<PersistentIDAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonTargetedID"
scope="SSSSSSSS" sourceName="eduPersonPrincipalName">
<DataConnectorDependency requires="echo"/>
<Salt>XXXXXXXXXXXXXXXXXXXXXXX</Salt>
</PersistentIDAttributeDefinition>
Replace the scope "SSSSSSSS" with the domain for which the attribute is to be asserted, e.g., "uni.ac.uk". The <Salt> is a constant, arbitrary value that you should choose once and keep secret. The value must be at least 16 characters long, otherwise the software will silently ignore it and expect the value to be supplied from a Java keystore. The Salt value is used to generate the persistent opaque identifier from the scope and some other attribute, normally the user id (eduPersonPrincipalName). Its purpose is to prevent attempts to work back from the opaque identifier to the user's identity by combining knowledge of the scope and the hash function used with an exhaustive search of the possible user ids.
The default Shibboleth attribute release policy does not release eduPersonTargetedID. You must therefore manually edit the arp.site.xml file to enable this feature, as described under Attribute Release below.
3. Shibboleth is not required at all simply to view the Internet2 Shibboleth Wiki, but you must log in from a federation to edit, and that requires eduPersonPrincipalName (to identify an individual editing account).
4. The Film & Sound Online service contains some restricted material not accessible to all users. Identity providers may assert a particular eduPersonEntitlement value to indicate that an individual user should have access to this material. The required value is listed in the rule set for Film & Sound Online in the section on Attribute Release below, which indicates the changes that may be needed in your ARP file, usually arp.sites.xml. In resolver.xml, simply use the default (unscoped) attribute definition for eduPersonEntitlement as shown below, where "xxxx" is the name of the data connector that links to your directory:
<SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonEntitlement"> <DataConnectorDependency requires="xxxx"/> </SimpleAttributeDefinition>
It is your responsibility to ensure that only users who meet the relevant licence conditions present this particular entitlement value.
5. Some services can make use of optional attributes if an identity provider offers them. For example, MIMAS Landmap and EDINA Digimap make use of the user's given name (givenName), surname (sn) and organisational unit (ou, treated as a Department name), if present. (Digimap uses these attributes, if present, to populate its initial online user registration form, not for ordinary logins). If such optional attributes are not supplied by the Identity Provider, the service may require the user to enter the same information manually, and these entries may need to be manually checked by the operator of the service.
6. Some services (e.g., ScienceDirect) grant access based on the name (entityID) of the identity provider used, rather than on the basis of user attributes. Therefore, it is not necessary to release any user attributes to such services to gain basic access, though some services may make use of additional attributes if they are supplied; for example, ScienceDirect can make use of eduPersonTargetedID.
7. EBSCO have recommended customers to contact their federation for the required attribute configuration. For the UK federation, first ensure that your identity provider releases eduPersonScopedAffiliation (ePSA) to the EBSCO SP as in the example "EBSCOHost service" <Rule> under Attribute Release below. Then go to EBSCO's online customer administration system (EBSCOadmin), select the "UK Higher Education" region, go to the "Shibboleth" configuration tab, ignore the "Shibboleth Entitlement" field and in the "Shibboleth Affiliation" field enter something like member@xxx.ac.uk, where xxx.ac.uk is the scope for your organisation. If your IdP will assert a value other than member (e.g., "student") then use that. If you are not already familiar with EBSCOadmin then EBSCO customer support may be willing to make these changes on your behalf.
8. An identity provider must present consistently either eduPersonTargetedID (recommended) or eduPersonPrincipalName (or both) to those EDINA services which require individual user registration. This allows logins to be related back to the user's registration details. Configuration of eduPersonTargetedID is described in note 2 above.
9. Some services (including EDINA services which require individual user registration, and MIMAS Landmap & CrossFire) will only grant access to users from an identity provider marked in the UK federation metadata as offering user accountability as defined in section 6 of the federation's Rules of Membership. Identity providers that offer user accountability are marked by having an <AccountableUsers> element within the <Extensions> element of the IdP's <EntityDescriptor>. Note that the Athens to Shibboleth gateway does not presently offer user accountability, therefore users of the gateway cannot access such services, including services that require individual user registration.
10. This is a test interface. It should be noted that the interface and attribute details may change.
11. The DreamSpark SP expects to receive a minimum of:
Attribute Release
An identity provider must ensure that its attribute release policy makes every required attribute visible to all the services its users should be able to visit. The default arp.site.xml file shipped with Shibboleth releases eduPersonScopedAffiliation to any service provider, which is all that is initially required by many services. Some services will work better, by supporting personalisation, if eduPersonTargetedID is also released. The default arp.site.xml file can be modified to release eduPersonTargetedID as follows (with eduPersonAffiliation also removed, as this unscoped attribute is of limited use across a federation):
<?xml version="1.0" encoding="UTF-8"?>
<AttributeReleasePolicy
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:mace:shibboleth:arp:1.0"
xsi:schemaLocation="urn:mace:shibboleth:arp:1.0 shibboleth-arp-1.0.xsd" >
<Description>Simplest possible ARP plus targeted ID.</Description>
<Rule>
<Target>
<AnyTarget/>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
</Rule>
</AttributeReleasePolicy>
Additional attributes, e.g., eduPersonEntitlement, can be released similarly.
If you later decide to modify the attribute release policy so that these attributes are not universally released, you will need to add individual <Rule>s for each service that users should have access to. You can copy the <Rule>s needed from the list of examples below:
<Rule>
<Description>CAB Abstracts and "Land, Life and Leisure" at EDINA</Description>
<Target>
<Requester>urn:mace:ac.uk:sdss.ac.uk:provider:service:nevis.ed.ac.uk</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>Digimap</Description>
<Target>
<Requester>https://geoshibb.edina.ac.uk/shibboleth</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
<!-- Following are optional but if present are used to pre-populate
the online user registration form. Since some of these are personal data,
the IdP should consider how it will meet its Data Protection Act
obligations before adding these to its configuration. -->
<Attribute name="urn:mace:dir:attribute-def:givenName">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:sn">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:mail">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:o">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:ou">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:title">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>Film and Sound Online service at EDINA</Description>
<Target>
<Requester>urn:mace:ac.uk:sdss.ac.uk:provider:service:emol.sdss.ac.uk</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonEntitlement">
<Value release="permit">urn:mace:ac.uk:sdss.ac.uk:entitlement:emol.sdss.ac.uk:restricted</Value>
</Attribute>
</Rule>
<Rule>
<Description>EIG service at EDINA</Description>
<Target>
<Requester>urn:mace:ac.uk:sdss.ac.uk:provider:service:eig.sdss.ac.uk</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>Internet2 Shibboleth Wiki</Description>
<Target>
<Requester>https://spaces.internet2.edu/shibboleth</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>MIMAS Landmap</Description>
<Target>
<Requester>urn:mace:ac.uk:sdss.ac.uk:provider:service:shibboleth-landmap.mimas.ac.uk</Requester>
</Target>
<!-- Minimal attribute set required is just ePPN: givenName, sn and ou are optional -->
<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>ScienceDirect</Description>
<Target>
<Requester>https://sdauth.sciencedirect.com/</Requester>
</Target>
<!--
No attributes are required: access is granted based on IdP entityID
but ePTI is leveraged if present.
-->
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>EBSCOhost service</Description>
<Target>
<Requester>http://shibboleth.ebscohost.com</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
</Rule>