7 Attribute Usage

7.1 Core Attributes

A core set of attributes has been identified that identity providers are recommended to support, and that service providers should consider when setting attribute requirements. There are two reasons for making these recommendations:

• to advise identity providers of the attributes commonly required by service providers as a condition for authorising access — a failure to supply these attributes is likely to result in a refusal of service from some service providers;

• to advise service providers of the attributes which identity providers are likely to be willing to supply — some institutions may be unable to supply attributes other than those in the recommended set.

Attributes in the core set have been chosen to be versatile, and should be sufficient for the great majority of applications.

The following are defined as core attributes; their individual use is described in the subsections following:

• eduPersonScopedAffiliation. This attribute indicates the user’s relationship (e.g., staff, student, etc.) with the organisation. For many applications, examination of this attribute is sufficient to determine whether the user has sufficient privilege to access the resource.

• eduPersonTargetedID. If a service provider is presented only with the affiliation of an anonymous subject, as provided by eduPersonScopedAffiliation, it cannot provide service personalisation or usage monitoring across sessions. These capabilities are enabled by the eduPersonTargetedID attribute, which provides a persistent user pseudonym, distinct for each service provider.

• eduPersonPrincipalName. This attribute is used where a persistent user identifier, consistent across different services, is required. It often corresponds to the user’s single sign-on (SSO) name, and may be useful for securing both internal institutional services and external services where access control lists are used.

• eduPersonEntitlement. This attribute enables an organisation to assert that a user satisfies an additional set of specific conditions that apply for access to a particular resource. A user may possess different values of the eduPersonEntitlement attribute relevant to different resources.

The core attributes are defined in the eduPerson specification ([eduPerson03], [eduPerson06], [eduPerson12]) and are exchanged using the MACE-Dir Attribute Profile for SAML 1.x, as described in [MACEAttr], section 2. Further information on the use of each of these attributes is given below.

7.1.1 Security Domains (Scopes)

The first three of the core attributes are structured as scoped attributes, and share a common syntax: local-part@security-domain, where local-part is attribute-specific and security-domain is a dotted string. The security domain contains a DNS name that the federation operator has verified is registered to the identity provider’s owner (or, in the case of an outsourced identity provider, the identity provider’s institutional client).

While the security domain has the appearance of a DNS name, it is not constrained to the semantics of a DNS name. In particular, for historical reasons the UK has issued pairs of DNS names to many institutions, and in DNS terms these are equivalent. For example, the University of Edinburgh has been issued both edinburgh.ac.uk and ed.ac.uk. As Shibboleth security domains, however, these names are distinct and cannot be used interchangeably. This is a potential source of configuration problems, which can be readily avoided if the organisation selects just one of its DNS names at all times (including when registering with other federations). This has no implications for the user interface, as security domains are used only in machine-to-machine exchanges. In our example, the University of Edinburgh has chosen to use the ed.ac.uk scope exclusively.

Institutions making use of outsourced identity providers are strongly recommended to use scopes based on domain names owned by themselves rather than names allocated by the identity provider of which they are a client. This allows for future flexibility in identity provision for the organisation: migration from one outsourced identity provider to another, or from an outsourced identity provider to in-house provision, is much more difficult when an organisation does not have control over its own scope.

Migrating from one identity provider to another is not simple even when the scope can remain unchanged: in particular, values of eduPersonTargetedID are relative to the issuing entity, and would become invalid after any such migration without significant co-ordination between identity providers and service providers.

Institutions in the HE/FE sector are recommended to use their principal institutional domain name as their scope.

All schools in the UK have a .sch.uk domain name suitable for use as a scope. Note that it is not necessary for the school to be using this domain name on the web or elsewhere in order for it to be used as a scope: the only requirement is that the federation operator can be satisfied that the domain name is registered to the school in question.

Although the .sch.uk name is recommended for use in most cases, it may also be appropriate for some schools to be given names under the domain name of a Local Authority or Regional Broadband Consortium in order to leverage existing methods used by LAs and RBCs to uniquely identify schools.

The federation operator is responsible for verifying that a federation member is authorised to make assertions for each security domain it registers before adding this information to the federation metadata. Shibboleth service provider software ensures that the only values of security domain which can be asserted by an identity provider are those present in the federation metadata for that identity provider.

7.1.2 eduPersonScopedAffiliation

This attribute enables an organisation to assert its relationship with the user. This addresses the common case where a resource is provided on a site licence basis, and the only access requirement is that the user is a bona fide member of the organisation, or a specific school or faculty within it.

The attribute is multi-valued (that is, a user can have more than one value for the attribute), and is structured as a scoped attribute, with the form affiliation@security-domain, where affiliation is one of a number of prescribed categories of user. The concept of security-domain is as described above (often taken as institutional DNS name).

7.1.2.1 eduPersonScopedAffiliation in the HE/FE Sector

The following table identifies the permitted values of eduPersonScopedAffiliation and provides the recommended interpretation for them in UK higher and further education. In particular, it indicates which category of user is typically regarded as authorised to access licensed materials according to the relevant Jisc Model Licence.

Defined value	Authorised User	Notes
student	yes	Undergraduate or postgraduate
staff	yes	UK term for all staff
faculty	yes	US term to distinguish teaching staff
employee	yes	Other than staff/faculty (e.g., contractor)
member	yes	Comprises all the categories named above
affiliate	no	Relationship short of full member
alum	no	Alumnus (graduate)
library-walk-in	yes	General library privileges

In general, other categories of user such as Honorary Staff or Visiting Scholar, who are treated as members with normal institutional privileges, would be assigned the value member. The value affiliate is defined as applying to those with whom the organisation has some dealings, but to whom no set of general membership privileges are extended. This could be applied to those with a short-term association with the organisation which is less close than member. Whether an affiliate is considered an authorised user for a specific service may vary from case to case.

Where a computer identity is assigned to a walk-in user, the identity provider must ensure that the user is physically present on approved premises before providing any authentication assertions for that user. This may be accomplished by IP address checking or by any other means.

7.1.2.2 eduPersonScopedAffiliation in the Schools Sector

The following table identifies the permitted values of eduPersonScopedAffiliation and provides the recommended interpretation for them in the UK schools sector.

Defined value	Notes
student	Pupil, student, learner
staff	All staff
faculty	Teaching staff
employee	Non-teaching staff
member	Comprises all the categories named above
affiliate	Relationship short of full member
alum	Alumnus (ex pupil)
library-walk-in	General library privileges

7.1.2.3 Generating and Interpreting eduPersonScopedAffiliation

Several values of eduPersonScopedAffiliation are regarded as being “contained” within other values: for example, the student value is contained within member.

It is recommended that identity providers have the ability either to maintain these multiple values for a given individual, or otherwise provide the ability to release either value as appropriate for a particular service provider. For example, although some service providers might require the release of the more specific student value, a different service provider that only requires the less specific member value should only be sent the less specific value. Releasing student in this case gives the service provider more information about the user than is required, raising privacy and data protection concerns.

Despite the recommendation above that identity providers should be conservative in what they send, service providers are recommended to be liberal in what they accept. For example, a service provider requiring member affiliation should also accept student, staff, etc. as alternatives.

Deployers of service provider entities should note that the precise meaning of the affiliation values may vary slightly from identity provider to identity provider. If this is not acceptable for the particular application being deployed and a precisely delimited category of users must be identified, a better solution may be the definition by the service provider of a custom value for the eduPersonEntitlement attribute (see below).

Members working with international partners should note that cultural differences mean that the staff and employee values may have different meanings to members of some other federations. The best solution to this issue is for service providers to avoid the use of these values when possible, and to explicitly confirm that they have a common understanding of the meaning of these values if they are required.

7.1.3 eduPersonTargetedID

Important note: the definition of the eduPersonTargetedID attribute has changed between [eduPerson03] and [eduPerson06], as have best practices surrounding its use. The recommendations here take the [eduPerson03] definition and the value encoding described under “Legacy name and Syntax” in [MACEAttr] section 2.3.2.1.2. However, recommendations are provided that should allow a smooth transition to the newer definition as appropriate.

A service provider may use eduPersonTargetedID to support aspects of its service that depend on recognising the same user from session to session. The most common use is to enable service personalisation, to record user preferences such as stored search expressions across user sessions. A secondary use is to enable tracking of user activity, to make it easier to detect systematic downloading of content or other suspected breaches of licence conditions.

The attribute enables an organisation to provide a persistent, opaque, user identifier to a service provider. For each user, the identity provider presents a different value of eduPersonTargetedID to each service provider to which the attribute is released. The attribute is defined as multi-valued (with one value for each service provider to which eduPersonTargetedID is released), though only a single value is ever released at a time. It is structured as a scoped attribute, with the form pseudonym@security-domain. The pseudonym is guaranteed to be unique within the context of the security-domain.

7.1.3.1 Generating eduPersonTargetedID

The eduPerson specification requires that a value of eduPersonTargetedID once assigned to a user for a given service provider shall never be reassigned to another user. Users and service providers should note, however, that not all identity providers may be able to guarantee that a user will always present the same value of eduPersonTargetedID; indeed, identity providers may offer their users the ability to generate new values of eduPersonTargetedID if they feel their privacy has been compromised.

There are two ways in which an identity provider may implement eduPersonTargetedID:

1. Algorithmic. This generates the pseudonym part of the eduPersonTargetedID value algorithmically from other attributes. This avoids the need for the identity provider to store the attribute value, as it can simply be regenerated dynamically as required.

   This has the disadvantage (for the end user and the service provider) that the value will change if any of the source attributes or the algorithm employed changes. Consequently, any user personalisation data such as stored search expressions would be lost. The user would also be unable to alter or delete any previously registered service alert requests.

2. Storage. An alternative solution is to store all values of eduPersonTargetedID ever issued. When a new value is required, this database is checked to prevent reassignment. Current values of eduPersonTargetedID are stored with the corresponding user entry. This is the most reliable way to ensure that the constraint on reassignment of values of eduPersonTargetedID is satisfied.

7.1.3.2 Interpreting eduPersonTargetedID

Although eduPersonTargetedID as described here is structured as a scoped attribute, this approach presents future compatibility problems due to the change in definition of this attribute between [eduPerson03] and [eduPerson06], along with the different value encodings described in [MACEAttr] section 2.3.2.1 and its sub- sections.

In order to be forwards-compatible with the new definition of eduPersonTargetedID, service providers should always treat an eduPersonTargetedID value as a triple composed of the following components:

• the entity name of the identity provider that created the value (this is not contained in the scoped value, but can be determined in the context of the attribute assertion as a whole),

• the entity name of the service provider or group for which the value was created (again, not contained in the scoped value, but a property of the service provider itself),

• the opaque string value that forms the local-part of the scoped value.

Note that in this revised view, the security-domain part of the scoped value is not part of the eduPersonTargetedID value, although it will be closely related to the first component in many circumstances.

On receipt of a scoped eduPersonTargetedID value, a service provider may either use it in conjunction with the two implicit entity name components described above, or decompose it to retrieve the local-part, and then combine it with the other components to form a new value. In the latter case, it is recommended that the new value is formed by concatenating the following elements:

• the entity name of the identity provider

• a single ‘!’ character

• the entity name of the service provider

• a single ‘!’ character

• the opaque string value that forms the local-part of the scoped value

The resulting string will contain the same value as the Shibboleth service provider software would present to an application on receipt of the SAML 2.0-based persistent identifier encoding of eduPersonTargetedID now recommended by [MACEAttr].

7.1.4 eduPersonPrincipalName

This attribute is used where a persistent user identifier, consistent across all services, is required and typically corresponds to the identifier which a user presents when authenticating to local institutional services (i.e., the user’s single-signon name or “netID”). The attribute is single-valued and structured as a scoped attribute, with the form local-name@security-domain. The security-domain component has the same semantics as the corresponding component in eduPersonScopedAffiliation. The local-name is guaranteed to be unique within the context of the security-domain.

It is recommended that a value of eduPersonPrincipalName previously associated with one individual should never be reassigned to another individual. Non-reuse may be assured by deriving eduPersonPrincipalName from a (non-repeating) staff number or student matriculation number, though care should be taken to ensure that any implicit information is not inadvertently leaked; for example, age may be encoded as part of the matriculation number. As in the case of eduPersonTargetedID, users and service providers should be aware that identity providers may not always be able to guarantee to present the same value of eduPersonPrincipalName.

7.1.5 eduPersonEntitlement

Values of eduPersonEntitlement take the form of a URI, most frequently using the “http” or “urn” schemes. For example:

http://publisher.example.com/contract/GL123

urn:mace:ac.uk:sdss.ac.uk:entitlement:emol.sdss.ac.uk:restricted

http://ukfederation.org.uk/entitlements/example

The meaning of a given value of eduPersonEntitlement is normally defined by a service provider. In the case of a value using the “http” scheme, it is recommended that the value resolve to a document giving the definition of the value. Having defined the meaning of the attribute value, the service provider then invites some or all identity providers to express that value for those users who satisfy the definition. In this way the service provider can delegate to the identity provider some or all of the responsibility for authorisation of access to a particular resource. Typically, this is used to assert entitlements over and above those enjoyed by other members of the organisation; for example, “Entitled to access the restricted material present in the Med123 resource”. In this case, the service provider trusts the organisation to verify that the user satisfies the (arbitrarily complex) authorisation conditions associated with the entitlement. This often involves an additional licence clause, where the organisation undertakes to assign the eduPersonEntitlement values according to agreed criteria.

Institutions are encouraged to consider the use of locally-defined values of eduPersonEntitlement to control access to local services. Such values are for internal use only, to model useful aspects of internal administrative operation, such as roles (e.g., “Member of the parking committee”) or specific authorisations (e.g., “Authorised to raise orders up to £1,000 in value”). Although the values are not released to external partners, a side-effect of using them should be to increase the trust an external service provider is likely to place in the identity and attribute assertions made by an organisation which relies on these same mechanisms for its internal administration.

7.1.5.1 Storing and Releasing eduPersonEntitlement

Because a particular value of eduPersonEntitlement often represents an entitlement to access a specific resource, identity providers should be capable of associating any number of entitlements with an individual user.

However, such entitlements may represent personal or even sensitive personal data about the individual. It is therefore important to control the release of individual values of eduPersonEntitlement closely, so that only service providers with a legitimate need for any given value of eduPersonEntitlement will have that value released to them. For example, values defined by a particular service provider should normally only be released back to that same service provider.

7.2 Attributes, Privacy and Data Protection

UK data protection law and the normal institutional obligation to preserve user privacy both require that information identifying individuals only be exchanged when strictly necessary. For most applications the attributes eduPersonScopedAffiliation or eduPersonTargetedID should be sufficient. Since these do not permit identification of an individual they should not raise privacy or data protection concerns. Identity providers should therefore expect to provide one or both of these attributes in most circumstances; service providers should normally request only these and other privacy preserving attributes. Any exchange of eduPersonPrincipalName will require both parties to comply with the data protection principles set out in the Data Protection Act 1998.

7.3 Subsidiary Attributes

The core attributes described here should be sufficient for most circumstances, and service providers are recommended to require only these attributes whenever possible in order to gain compatibility with the maximum number of identity providers.

However, it is recognised that it may become necessary for the federation to list small numbers of additional attributes that, while not likely to be implemented universally enough to be recommended as core attributes, are nevertheless of use to sufficient federation members for a standard definition to be useful. Such subsidiary attributes will be defined here; none are currently defined.

7.4 Sources of Additional Attributes

Where the core and subsidiary attribute groups defined by the federation do not meet the particular needs of regional and subject-based groups, it is possible for such groups to define and use their own attribute groups. In these cases, it is strongly recommended that service providers and identity providers make use of existing attribute definitions from the following sources before defining custom attributes:

• the eduPerson object class ([eduPerson12]),

• the person and organizationalPerson object classes (X.521),

• the inetOrgPerson object class (RFC2798).

All attributes should be encoded according to the recommendations of [MACEAttr] sections 2.2 and 2.3.

Note that inclusion in the above list does not imply endorsement by the federation of the use of any specific attributes from the listed object classes. Federation members should carefully consider the privacy and data protection implications of any attribute definition before making use of it.

7.5 Custom Attributes

The expectation for any newly invented attribute must be that it will not be widely implemented by members of the federation. It is therefore recommended that federation members only define new attributes as a last resort when no suitable definition exists elsewhere.

It is strongly recommended that any new attribute definitions follow the SAML attribute naming conventions of [MACEAttr] section 2.2, and the value encoding conventions of [MACEAttr] section 2.3.

Federation members should carefully consider the privacy and data protection implications of any newly invented attribute.

7.6 Working Without Attributes

Most Shibboleth service providers make authorisation decisions on the basis of a collection of attributes issued by the identity provider in respect of the authenticated user. It is, however, possible to authorise access for any user authenticated by a particular identity provider: any authentication statements from that identity provider are therefore given equal weight.

This authorisation model is recommended for use only when the service provider has specific assurance that the identity provider in question only issues authentication assertions for individuals acceptable to the service provider.

Authorisation without attributes is not recommended for general use within the federation, where:

• Institutional identity providers often provide identities for individuals who are only indirectly connected with the organisation, such as contractors.

• Many institutions may share the same outsourced identity provider.

Instead, scoped attributes such as eduPersonScopedAffiliation should be used to establish the individual’s relationship with the organisation, and to distinguish between organisations making use of the same shared identity provider.

Documents

• Current TRP (1.6)
• Current FTS (1.6)
• Current MDRPS (20130902)

Resources

• Federation Site
• About This Site