TIDF – TARENA identity Federation

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

Identity provider (IdP) – system component that issues Assertions on behalf of End Users who use them to access the services of SPs.

Service provider (SP) – system component that evaluates the Assertion from an IdP and uses the information from the Assertion for controlling access to protected services. Synonym for an AAI-enabled Resource, although used in a more technical sense.

SSO (Single Sign-On) is a property of access control of multiple related, but independent software systems. With this property a user logs in once and gains access to all systems without being prompted to log in again at each of them.

LDAP (Lightweight Directory Access Protocol) is a set of protocols for accessing on-line information directories.

SAML (Security Assertion Markup Language) is an open standard describing security assertions or claims. The relevant version of the specification is SAML 2.

SAML entity is a party sending or receiving SAML messages. Both IdP’s and SP’s are SAML entities.

Entity Metadata is SAML metadata for a single SAML entity.

Federation Metadata is a collection of entity metadata, i.e. the collection of metadata for all IdP’s and all SP’s in the Federation. As such, the Federation metadata serves as the technical definition of the Federation.

Attributes: a person’s identity is a collection of his or her attributes. Examples are someone’s date of birth, name, color of his or her eyes, etc… Exchange of attributes is the essence of SAML: the IdP knows a number of attributes about people; SP’s need a subset of a these attributes to decide whether this person is authorized for the service concerned. The SAML protocol describes how to exchange such information between IdP and all SP.
Attribute Release Policy is the policy, set by the IdP, describing which attributes are “released” to the SP whenever the SP requests authentication. A policy can be set as a general default; also it can be set for specific services. In the latter case the personal data released to the SP can be limited to what the SP needs.

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.
2. Protocols used
2.1. TIDF Federation SAML WebSSO Technology Profile

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

All entity metadata MUST fulfill the SAML V2.0 Metadata Interoperability Profile Version 1.0 or any later version.

All IdP’s and SP’s MUST fulfill the SAML 2.0 Interoperability Deployment Profile.

All SAML attribute names SHOULD be represented using either the urn:oid or http(s) URI scheme namespaces.

All IdP’s MUST implement the Shibboleth Scope Metadata extension as defined in the Shibboleth Metadata Schema. The Scope value MUST be a string equal to a DNS domain owned by the entity that is responsible for the IdP (see section 4.2 below).

All SP’s SHOULD implement checks against the Shibboleth Scope Metadata extension when processing scoped attributes.

Use of Shibboleth 3.x software is recommended for mitigating incompatibility risks, but not mandatory.
2.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).

Every Federation member (IdP or SP) MUST notify the Federation Operator whenever a certificate key pair is compromised. The entity involved will then be removed from the Federation metadata. When the issue is fixed, the new entity metadata will be included in the Federation metadata. An on-site audit might be required for verification of the fix.

IdP’s/SP’s that cease operations will be removed from the Federation metadata. A notification MUST be sent to TIDF contact: support(at)tidf.tj
A minimum key size of 2048 bits is required.

3. 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.
3.1. Publication

The Federation Operator will publish the Federation metadata. Its URL is given on the Metadata page. It is mandatory to refresh the metadata in IdP and SP installation every 24 hours, or at a higher refresh frequency.
3.2. Digital signature

The federation metadata files are digitally signed with the TIDF Metadata Signer certificate.
3.3. Submitting entity metadata

Every IdP and every SP has its own piece of metadata (the “entity metadata”), which is usually generated at the installation of the software. To submit or revoke entity metadata from the TIDF Federation, please request TIDF contact: support(at)tidf.tj
4. 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:

    inetOrgPerson, as defined in RFC 2798
    (attributes givenName, sn, displayName, common name (cn), mail);

    eduPerson, developed by MACE
    (attributes eduPersonAffiliation, eduPersonScopedAffiliation, SAML2 Persistent NameID (eduPersonTargetedID), eduPersonPrincipalName, eduPersonEntitlement);

    SCHAC, developed by TERENA
    (attribute schacHomeOrganization).

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.
4.1. Object class inetOrgPerson

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

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

4.1.2. sn

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

4.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 authorization.

4.1.4. common name (cn)

It is typically the person’s full name.

4.1.5. mail

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

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

Attributes eduPersonAffiliation and eduPersonScopedAffiliation are subject to a controlled vocabulary: only a limited set of values with specific meanings can be used here. See section 4.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.

4.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 the 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 the library-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 of library-walk-in, though specific terms may vary.

4.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 4.2.1) and security-domain is institutional DNS name as described above, usually stored at schacHomeOrganization (see section 4.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.

4.2.3. SAML2 Persistent NameID (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 personalization 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.

4.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: “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.

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

4.3.1 schacHomeOrganization

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

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

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.
6. Acknowledgments

This work is based on the

   eduGAIN Policy Framework Attribute Profile (recommended) v 1.4. ©2015 GÉANT.
   Hungaranet
   SimpleSAMLphp Uninett
   Surfnet OpenConext
   PyFF