Notes on Attribute Usage

This page contains the aggregates notes from the table on our Attribute Usage page, followed by guidance on attribute release for a range of IdPs.

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

While a Shibboleth identity provider can generate eduPersonScopedAffiliation statically by setting the required value in attribute-resolver.xml, this should only be done when it is known that all users are authorised. Otherwise, the value can be picked up from your LDAP / Active Directory as described on the IdP setup page.

Users of other IdP software should check their documentation.

2. Many services can make use of 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 in Attribute Usage.

For a Shibboleth IdP, generation of eduPersonTargetedID in attribute-resolver.xml is described on the IdP setup page.

Release of eduPersonTargetedID by attribute-filter.xml is described further down the same page.

Users of other IdP software should check their documentation.

3. Shibboleth is not required at all simply to view the Shibboleth Project Wiki, but you must log in from a federation to edit, and that requires eduPersonPrincipalName (to identify an individual editing account).

4. JISC MediaHub contains some restricted material not accessible to all users. Identity providers may release a particular eduPersonEntitlement value on behalf of individual users who should have access to this material.

The required value is "urn:mace:ac.uk:sdss.ac.uk:entitlement:emol.sdss.ac.uk:restricted". Please check your IdP's documentation for further details.

Additionally, a declaration by sub-licensees requiring access to medically restricted material must be completed. The declaration form can be found at http://www.jisc-collections.ac.uk/mediahub-declaration

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 an eduPersonScopedAffiliation (ePSA) value of "member@xxx.ac.uk" (where "xxx.ac.uk" is the scope for your organisation) to the EBSCO SP.

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 member@xxx.ac.uk. If you are not already familiar with EBSCOadmin then EBSCO customer support may be willing to make these changes on your behalf.

8. When a service provider permits or requires individual user registration, they will require the identity provider to present eduPersonTargetedID or eduPersonPrincipalName. This allows logins to be related back to the user's registration details.

NB: in general we recommend the use of eduPersonTargetedID as presentation of eduPersonPrincipalName has implications under the DPA. Configuration of eduPersonTargetedID is described in note 2 above.

9. Some services (including EDINA services which require individual user registration) 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>.

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:

12. This service provider requires that an identity provider presents eduPersonTargetedID. This allows logins to be related back to the user's registration details. Configuration of eduPersonTargetedID is described in note 2 above.

13. An IdP must release one of:

• eduPersonPrimaryOrgUnitDN
• urn:mace:dir:attribute-def:eduPersonPrimaryOrgUnitDN
• urn:mace:dir:attribute-def:eduPersonScopedAffiliation

AND one of:

• id
• urn:mace:dir:attribute-def:eduPersonTargetedID

14. At least one attribute must be provided.

15. On the user’s first visit to this service's WAYF page, a cookie is dropped on the user’s machine with the entityID of the IdP they selected. Subsequently, the WAYF will look for this cookie and automatically redirect the user to their IdP if it is found, so in some respects it acts like a WAYFless URL. The URL is generated dynamically from the last refresh of the online metadata, so any change in the URL of the IdP or SP authentication points should be picked up automatically.

16. RefWorks requires a unique identifier for each user, to associate the user with their RefWorks account. This unique identifier can be either an eduPersonTargetedID (ePTID) or an eduPersonPrincipalName (ePPN). Each IdP may choose to release either the ePTID or the ePPN for their users. Most IdPs choose to release the ePTID, but some prefer to release the ePPN instead. Please note, though, that ePPN may be considered "personal information".

17. RefWorks can optionally receive an eduPersonScopedAffiliation (ePSA) for each user, which we would use to authorize the user. Typical authorized values would be "student", "faculty", and "staff", though some institutions simply use "member" for all and only users authorized to use RefWorks. An ePSA isn't necessary, if the IdP only releases unique identifiers for users who are authorized to use RefWorks. We leave it to the IdP to decide whether to release the ePSA or not.

18. eduPersonEntitlement is an optional attribute that can be used to provide either a list of enrolled module codes (see FAQ question 2 at http://support.talisaspire.com/entries/382415-devolved-authentication-guidelines-for-talis-aspire), or devolved constraints (see http://support.talisaspire.com/entries/445432-implementing-devolved-constraints) to Talis Aspire.

19. Please refer to http://jusp.mimas.ac.uk/entitlements/siterep/ for further information. Mimas is able to provide additional information on this aspect if required and is keen to work with institutions who wish to implement this. Please email the helpdesk jusp at mimas.ac.uk for assistance.

20. WAYFless URLs for ProQuest SPs

To find your organisation's ProQuest account ID, log in with your IdP and local credentials in the usual manner. Once you've clicked on any link (such as one of the subject area links), you will see a string similar to

 ?accountid=XXXXXX

at the end of the URL in the address bar. Appending this to any URL on the site will take you to a login page using your own IdP.

For example,

 http://search.proquest.com/shibboleth?accountid=XXXXXX

Will take you to a login page that will allow you access everything on the platform you're licensed for.

Deep Linking

For a link to the top level of PIO (Periodicals Index Online), use

 http://search.proquest.com/pio/shibboleth?accountid=XXXXXX

To link to a journal

 http://search.proquest.com/publication/1798/shibboleth?accountid=XXXXXX

To link to the same journal in the PIO section of the site

 http://search.proquest.com/pio/publication/1798/shibboleth?accountid=XXXXXX

Finally, to link to an article directly from the platform level

  http://search.proquest.com/docview/1295755308/shibboleth?accountid=XXXXXX

We would recommend that libraries use database-level links on portal pages and directories, but use the generic links for documents and journals.

21. WAYFless URLs for `"BUFVC" SPs

There have been some changes to BUFVC's servers and SP, so as a result the way their WAYFless URLs are constructed have had to change.

In particular, they are now using SP-side WAYFless URLs: these are generally considered to be less brittle and will not need to be altered if you update or replace your IdP.

All of these URLs are based on the same template

https://login.bufvc.ac.uk/wayfless.php?entityID=$INSTITUTION_IDP&target=$BUFVC_SERVICE

with two parameters: $INSTITUTION_IDP and $BUFVC_SERVICE

Create the first by URL-encoding your IdP's entityID as registered in the federation and listed in BUFVC's members database, so that https://idp.rummidge.ac.uk/entity would become https%3a%2f%2fidp.rummidge.ac.uk%2fentity.

The second should be replaced with any of the BUFVC Services you'd like to have direct access to. See below the current collections:

BoB: https%3A%2F%2Flearningonscreen.ac.uk%2Fondemand
RADIO: http%3a%2f%2fbufvc.ac.uk%2ftvandradio%2findependent-radio
ThisWeek: http%3a%2f%2fbufvc.ac.uk%2ftvandradio%2fthisweek
TRILT: http%3a%2f%2fbufvc.ac.uk%2ftvandradio%2ftrilt
TVTip: http%3a%2f%2fbufvc.ac.uk%2ftvandradio%2ftvtip

Examples for some BUFVC Services, these already contain the "target" parameter, but you will need to add your own IdP's entityID:

BoB: https://login.learningonscreen.ac.uk/wayfless.php?entityID=INSTITUTION_IDP&target=https%3A%2F%2Flearningonscreen.ac.uk%2Fondemand

BUFVC: https://login.bufvc.ac.uk/wayfless.php?entityID=INSTITUTION_IDP&target=http%3A%2F%2Fbufvc.ac.uk

RADIO: https://login.bufvc.ac.uk/wayfless.php?entityID=INSTITUTION_IDP&target=http%3A%2F%2Fbufvc.ac.uk%2Ftvandradio%2Findependent-radio

ThisWeek: https://login.bufvc.ac.uk/wayfless.php?entityID=INSTITUTION_IDP&target=http%3A%2F%2Fbufvc.ac.uk%2Ftvandradio%2Fthisweek

TRILT: https://login.bufvc.ac.uk/wayfless.php?entityID=INSTITUTION_IDP&target=http%3A%2F%2Fbufvc.ac.uk%2Ftvandradio%2Ftrilt

TVTip: https://login.bufvc.ac.uk/wayfless.php?entityID=INSTITUTION_IDP&target=http%3A%2F%2Fbufvc.ac.uk%2Ftvandradio%2Ftvtip

22. Attributes for "Open Cloud Consortium" SPs

eduPersonPrincipalName: The OSDC Console first checks for the ePPN attribute and then uses that as a users primary identifier. To access the Open Science Data Cloud Console an identity provider needs to release either the eduPersonTargetedID or eduPersonPrincipalName (EPPN) attributes.

eduPersonTargetedID: If ePPN is not present this attribute is used to identify users. Identity providers may prefer to only release the eduPersonTargetedID attribute.

23. eduPersonScopedAffiliation values

This SP requires the eduPersonScopedAffiliation attribute to release the student affiliation for users that the organisation identifies as being students. This may require additional configuration by IdP operators.

Attribute Release

An identity provider must ensure that its attribute release policy makes the appropriate required attributes visible to each of the services its users should be able to visit.

Which attributes to release?

Different federations operate with different sets of core attributes. Those used by the UK federation are discussed in section 7 of the Technical Recommendations for Participants document, but in general it is sufficient to release eduPersonScopedAffiliation for those SPs that do not require personalisation of any kind, along with eduPersonTargetedID for those that do. Some SPs may require eduPersonEntitlement to be released (contact the appropriate publisher for the actual value). Finally, some SPs may require eduPersonPrincipalName, but before releasing this attribute you should read section 3 of the Recommendations for Use of Personal Data document.

We also have a general guide to the use of attributes which has background information on the above documents.

How to release attributes

Attribute release is a two part process. The value of an attribute to be released can be generated statically (not recommended unless you are sure that all your users are entitled to that particular value), looked up from a database or directory, or generated from values that have been looked up. Once the attributes have been generated, they can be filtered by a set of rules to ensure that only the appropriate attributes are released to each SP.

Guidance on attribute generation and filtering for the more usual IdPs may be found at the links below:

Shibboleth 4.x IdP

https://wiki.shibboleth.net/confluence/display/IDP4/AttributeResolverConfiguration

https://wiki.shibboleth.net/confluence/display/IDP4/AttributeFilterConfiguration

Please note: earlier versions of the Shibboleth IdP are EOL and the links are given for information only

Shibboleth 3.x IdP

https://wiki.shibboleth.net/confluence/display/IDP30/AttributeResolverConfiguration

https://wiki.shibboleth.net/confluence/display/IDP30/AttributeFilterConfiguration

Shibboleth 2.* IdP

https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttribute

https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttributeFilter

OpenAthens MD

https://docs.openathens.net/display/MD/Attribute+release

OpenAthens LA

https://docs.openathens.net/display/public/LA/Attributes

https://docs.openathens.net/display/LA/Release+policies

If you are using any other IdP software, please check its documentation or with the vendor.