PEANO Federation

Technical Rules

1. Introduction

This document describes technical requirements and procedures for the PEANO Federation. It is a technical complement to the PEANO Federation Policy. Wherever this document is not consistent with the Policy, the Policy takes precedence.

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [0].

3. Protocols used

3.1. PEANO Federation SAML WebSSO Technology Profile

The PEANO Federation is realized using SAML V2.0 Web Browser SSO Profile [1] which defines a standard that enables IdP's and SP's to create and use web SSO services using SAML.

Use of Shibboleth 2.x [5] software is recommended for mitigating incompatibility risks, but not mandatory.

3.2. SAML entity certificate requirements

Every SAML entity needs a certificate in order to sign and/or encrypt SAML messages. Usually a self-signed certificate is created during a default install. The certificate is part of the entity metadata, and will have to be published as part of the Federation metadata (see further).

4. Federation metadata

One of the core services is the publication and distribution of SAML 2.0 metadata. The metadata is a collection of all IdP's and all SP's in the Federation, including technical elements like URL's and X.509 certificates.

4.1. Publication

The Federation Coordinator will publish the Federation metadata. Its URL is given on the Technical information page. It is mandatory to refresh the metadata in IdP and SP installation every 24 hours, or at a higher refresh frequency.

4.2. Digital signature

The Federation Coordinator will sign the Federation metadata before publication. It will use a certificate from URAN using the common name "PEANO.URAN.UA Metadata Signing Key".

4.3. Submitting entity metadata

Every IdP and every SP has its own piece of metadata (the "entity metadata"), which is usually generated at installation of the software. To submit or revoke entity metadata from the PEANO Federation, please request PEANO contact:

5. Attribute schema

SAML 2.0 transmits identity data from IdP's to SP's in the form of attributes, defined in attribute schema. IdP's and SP's are free to use any attributes in any schema that fits their needs, but to make the Federation truly interoperable, IdP's SHOULD be able to produce the limited set of attributes based on the following object classes and LDAP schemas:

The implementation of the IdP infrastructure does not have to take place completely using the LDAP/X.500 standards. Some attributes MAY be dynamically generated by IdP's based on other attribute values.

Application developers are advised to produce fail-safe code, such as implementing an appropriate fall-back mechanism if an IdP is unable to provide an attribute that the SP requests.

5.1. Object class inetOrgPerson

inetOrgPerson is an LDAP object class, standardised in order to have a common schema for personal data. This schema is included in most directory implementations.

5.1.1 givenName

The end userís first name or (optionally) combination of his/her first name and patronymic. Only letters, hyphens and spaces are allowed.

5.1.2. sn

The end userís surname (family name). Only letters, hyphens and spaces are allowed.

5.1.3. displayName

The preferred name of a person to be used when displaying entries. Since this value is not guaranteed to be either unique or persistent it is not recommended to be used as a unique key or for authorisation.

5.1.4. mail

The end userís valid personal mail address (not a shared mailbox). It is necessary to be able to reach the end user.

5.2. Object class eduPerson

The eduPerson object class is defined as an extension to the inetOrgPerson object class, adding attributes relevant for persons in an educational environment.

Atrributes eduPersonAffiliation and eduPersonScopedAffiliation are subject to a controlled vocabulary: only a limited set of values with specific meanings can be used here. See section 5.2.1 for details.

Attributes eduPersonScopedAffiliation and eduPersonPrincipalName are structured as scoped attributes, and share a common syntax: local-part@security-domain, where local-part is attribute-specific and security-domain ("Scope") is a dotted string equal to a DNS domain owned by the entity that is responsible for the IdP. If an IdP owns more than one DNS domain it selects just one of its DNS names at all times.

5.2.1. eduPersonAffiliation

This attribute indicates the userís relationship with the organization. For many applications, examination of this attribute is sufficient to determine whether the user has sufficient privilege to access the resource. The permissible values for eduPersonAffiliation are: faculty, student, staff, alum, member, affiliate, employee, library-walk-in. Semantics of these values are described below.

5.2.2. eduPersonScopedAffiliation

This attribute enables an organization 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 organization, 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 usually stored at eduPersonAffiliation (see section 5.2.1) and security-domain is institutional DNS name as described above, usually stored at schacHomeOrganization (see section 5.3.1).

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 IdPís 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 SP. For example, although some SPís might require the release of the more specific student value, a different SP that only requires the less specific member value should only be sent the less specific value. Releasing student in this case gives the SP more information about the user than is required, raising privacy and data protection concerns.

Despite the recommendation above that IdPís should be conservative in what they send, SPís are recommended to be liberal in what they accept. For example, a SP requiring member affiliation should also accept student, staff, etc. as alternatives.

5.2.3. eduPersonTargetedID

If a SP 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, shared between an IdP and SP, and distinct for each SP. An IdP uses the appropriate value of this attribute when communicating with a particular SP, and does not reveal that value to any other SP.

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

For each user, the IdP presents a different value of eduPersonTargetedID to each SP to which the attribute is released. The attribute is defined as multi-valued (with one value for each SP to which eduPersonTargetedID is released), though only a single value is ever released at a time.

This attribute does not meet requirements for human palatability or readability. It is designed to preserve the user's privacy and inhibit the ability of multiple unrelated services from correlating user activity by comparing values. It is therefore REQUIRED to be opaque, having no particular relationship to the user's other identifiers, such as a local username.

A value of eduPersonTargetedID once assigned to a user for a given SP MUST NOT be reassigned to another user. Users and SPís should note, however, that not all IdPís may be able to guarantee that a user will always present the same value of eduPersonTargetedID; indeed, IdPís 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 IdP may implement eduPersonTargetedID:

  1. Algorithmic. This generates a pseudorandom or hash function value algorithmically from other attributes. This has the disadvantage (for the end user and the SP) 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.

5.2.4. eduPersonPrincipalName

This attribute is used where a persistent user identifier, consistent across different services, is required. It often corresponds to the userís SSO name, and may be useful for securing both internal institutional services and external services where access control lists are used.

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.

A value of eduPersonPrincipalName previously associated with one individual MUST NOT ever be reassigned to another individual. As in the case of eduPersonTargetedID, users and SPís should be aware that IdPís may not always be able to guarantee to present the same value of eduPersonPrincipalName.

5.2.5. eduPersonEntitlement

This attribute enables an organization 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, thus IdPís should be capable of associating any number of entitlements with an individual user.

A value of eduPersonEntitlement is URI (either URL or URN) that indicates a set of rights to specific resources. For example: "" or "". A simple example would be a URL for a contract with a licensed resource SP.

The meaning of a given value of eduPersonEntitlement is normally defined by a SP. 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 SP then invites some or all IdPís to express that value for those users who satisfy the definition. In this way the SP can delegate to the IdP some or all of the responsibility for authorisation of access to a particular resource. In this case, the SP trusts the organization to verify that the user satisfies the (arbitrarily complex) authorisation conditions associated with the entitlement. This often involves an additional licence clause, where the organization undertakes to assign the eduPersonEntitlement values according to agreed criteria.a.

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 SPís with a legitimate need for any given value of eduPersonEntitlement will have that value released to them. For example, values defined by a particular SP should normally only be released back to that same SP.

5.3. Object class SCHAC

The SCHAC (SCHema for ACademia) aims to define and promote common schemas in the field of higher education to facilitate inter-institutional data exchange.

5.3.1 schacHomeOrganization

A dotted string equal to a DNS domain owned by the entity that is responsible for the IdP.

6. Protection of privacy and personal data when releasing attributes

IdP's SHOULD NOT release all attributes to all SP's for all end users. Information identifying individuals MUST only be exchanged when necessary. A procedure for controlled attribute release and minimal disclosure is defined in the GÉANT Data protection Code of Conduct [9].

For most applications the attributes eduPersonScopedAffiliation or eduPersonTargetedID are sufficient. Since these do not permit identification of an individual they do not raise privacy or data protection concerns. IdPís should therefore expect to provide one or both of these attributes in most circumstances; SPís 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.

7. References

[0] RFC 2119. Key words for use in RFCs to Indicate Requirement Levels.
S. Bradner, Harvard University, March 1997

[1] Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0.
OASIS Standard, 15 March 20055

[2] SAML V2.0 Metadata Interoperability Profile Version 1.0.
Committee Specification 01, 4 August 200909

[3] SAML 2.0 Interoperability Deployment Profile

[4] urn:mace:shibboleth:metadata:1.0

[5] Shibboleth Consortium

[6] RFC 2798. Definition of the inetOrgPerson LDAP Object Class.
M. Smith, Internet Engineering Task Force, Apr. 2000, updated by RFCs 3698, 4519, 4524.

[7] eduPerson Object Class Specification

[8] SCHAC, SCHema for ACademia. TERENA.

[9] GÉANT Data protection Code of Conduct

8. Acknowledgments

This work is based on the

Special gratitude to Peter Schober, ACOnet (Austrian Academic Computer Network) for consultations and discussions in the preparation of this document