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.
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].
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.
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).
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.
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.
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".
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:
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.
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.
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:
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.
- faculty
This affiliation can be assigned to workers whose primary role is teaching or research.
- staff
This affiliation can be assigned to workers other than teachers or researchers such as administrative, technical and auxiliary personnel.
- employee
This affiliation can be assigned to anyone who is employed by the organization including faculty and staff, and also contractors, interns, uncontracted workers, volunteers, etc. (Note that there are conflicting definitions of staff and employee from country to country. That make those values particularly unreliable in any international context.)
- student
This affiliation can be assigned to those who are studying at undergraduate or postgraduate level.
- member
This affiliation is intended to include faculty, staff, student, and other persons with a basic set of privileges that go with membership in the university community (e.g., they are given library privileges and/or vpn accounts). The member affiliation MUST be asserted for people carrying one or more of the following affiliations: faculty, staff, employee or student.
- alum
Referring to alumnus. This affiliation can be assigned to those who are former students of the organization. Some variation is common, in whether individuals who did not complete their course are considered alumni. Holders of the affiliation alum are not typically members since they are not eligible for the full set of institutional privileges enjoyed by faculty, staff and students.
- affiliate
This affiliation indicates that the holder has some definable affiliation to the university NOT captured by any of faculty, staff, student, alum and/or member. Typical examples might include event volunteers, parents of students, guests and external auditors. There are likely to be widely varying definitions of affiliate across institutions.
- library-walk-in
This term was created to cover the case where physical presence in a library facility grants someone access to electronic resources typically licensed for faculty, staff and students. In recent years thelibrary-walk-in provision has been extended to cover other cases such as library users on the campus network, or those using on-campus workstations. Licensed resource providers have often been willing to interpret their contracts with licensees to accept this broader definition oflibrary-walk-in, though specific terms may vary.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) andsecurity-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:
- 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.
- 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 . Thesecurity-domain component has the same semantics as the corresponding component in eduPersonScopedAffiliation. Thelocal-name is guaranteed to be unique within the context of thesecurity-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: "http://publisher.example.com/contract/GL123" or "urn:mace:washington.edu:confocalMicroscope". 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.
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.
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.
[0]
RFC 2119. Key words for use in RFCs to Indicate Requirement Levels.
S. Bradner, Harvard University, March 1997
http://www.ietf.org/rfc/rfc2119.txt
[1]
Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0.
OASIS Standard, 15 March 20055
http://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf
[2]
SAML V2.0 Metadata Interoperability Profile Version 1.0.
Committee Specification 01, 4 August 200909
http://docs.oasis-open.org/security/saml/Post2.0/sstc-metadata-iop.pdf
[3]
SAML 2.0 Interoperability Deployment Profile
http://saml2int.org/profile/current/
[4]
urn:mace:shibboleth:metadata:1.0
https://svn.shibboleth.net/cpp-sp/branches/Rel_1_3/schemas/shibboleth-metadata-1.0.xsd
[5]
Shibboleth Consortium
http://shibboleth.net
[6]
RFC 2798. Definition of the inetOrgPerson LDAP Object Class.
M. Smith, Internet Engineering Task Force, Apr. 2000, updated by RFCs 3698, 4519, 4524.
http://www.ietf.org/rfc/rfc2798.txt
[7]
eduPerson Object Class Specification
https://www.internet2.edu/products-services/trust-identity-middleware/eduperson-eduorg/eduperson-eduorg-documentation/
[8]
SCHAC, SCHema for ACademia. TERENA.
http://www.terena.org/activities/tf-emc2/schac.html
[9]
GÉANT Data protection Code of Conduct
http://www.geant.net/uri/dataprotection-code-of-conduct/Pages/default.aspxx
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