HEAL-Link Identity Provider Proxy integration guide for Service Providers

Overview

HEAL-Link enables access to electronic resources (electronic journals, e-books and bibliographic databases) for Greek Universities, Research Institutions and their users. Specifically, HEAL-Link operates a SAML 2.0 Identity Provider/Service Provider (IdP/SP) Proxy service that acts as a central hub between the IdPs of HEAL-Link members, and the SPs that support federated access to electronic resources. This page provides information about connecting an SP to the HEAL-Link IdP proxy service in order to allow user logins through HEAL-Link and to receive user attributes.

Metadata exchange

SAML authentication relies on the use of metadata. Both parties (you as the SP and the HEAL-Link IdP) need to exchange metadata in order to establish technical trust. The metadata include information such as the location of the service endpoints that need to be invoked, as well as the certificates that will be used to sign SAML messages.

In order to configure metadata exchange with the HEAL-Link IdP it is necessary to provide the following information about your SP:

entityID
Metadata URL

Providing the metadata URL is optional if your metadata is already published to eduGAIN. If your SP is registered in some federation but it is not published to eduGAIN, it is recommended to provide the URL to signed federation metadata aggregate and the respective signing certificate. We can then cherry pick the metadata based on the SP entityID.

The URL should employ the HTTPS scheme, in which case server certificate verification will be performed, so you need to ensure that visiting the URL using a modern browser does not throw any warnings or errors.

The provided metadata must adhere to the metadata specification for SAML 2.0.

The respective information for the HEAL-Link IdP is provided as follows:

entityID: https://aai.heal-link.gr/proxy/saml2/idp/metadata.php
Metadata URL: https://aai.heal-link.gr/proxy/saml2/idp/metadata.php

The metadata is signed with the following key:

The aggregate metadata of downstream entities is also provided at the following URL, for your reference. These are the IdPs of HEAL-Link members connected to the HEAL-Link IdP/SP proxy service.

https://aai.heal-link.gr/proxy/proxied-entities

Attributes

The HEAL-Link IdP Proxy will return a SAML assertion to the SP, providing information about an authenticated user. The following table lists the supported attributes and indicates their availability:

Attribute friendly name	Attribute Name	Description	Example value	Availability
eduPersonEntitlement	`urn:oid:1.3.6.1.4.1.5923.1.1.1.7`	A value of `urn:mace:dir:entitlement:common-lib-terms` indicates the user's right to access electronic resources	`urn:mace:dir:entitlement:common-lib-terms`	Subject to attribute release by home IdP
authnAuthority	`urn:oid:1.3.6.1.4.1.16515.2.5.1.1`	One or more identifiers (entityID) of authentication authorities that were involved in the authentication of the user (not including the assertion issuer, i.e the HEAL-Link IdP)	`https://login.auth.gr/saml2/idp/metadata.php`	Always
eduPersonScopedAffiliation	`urn:oid:1.3.6.1.4.1.5923.1.1.1.9`	The user's affiliation within a particular security domain in broad categories such as student, faculty, staff, alum etc.	`faculty@med.auth.gr`	Subject to attribute release by home IdP
schacHomeOrganization	`urn:oid:1.3.6.1.4.1.25178.1.2.9`	The domain name for the user's home organisation	`auth.gr`	Subject to attribute release by home IdP
mail	`urn:oid:0.9.2342.19200300.100.1.3`	The user's e-mail address (one or more)	`johndoe@auth.gr`	Subject to attribute release by home IdP

Mapping users to their home organizations

An SP may need to determine the home organization of a user authenticated through the HEAL-Link IdP proxy. The SAML assertion returned to the SP is issued by the proxy: the issuer will match the entityID of the HEAL-Link IdP proxy. This means it can not be used to match the entityID of the home organization, i.e. the IdP for the HEAL-Link member who authenticated the user. There are other ways to do this mapping, provided as follows:

Use the schacHomeOrganization attribute value, which should provide the well-known domain name for the home organization. It should be noted this value is not controlled or enforced in any way by the proxy.
Use the eduPersonScopedAffiliation attribute value, in particular the scope (security domain) contained therein, for a similar lookup. It should be noted that scopes for downstream entities are not listed in the HEAL-Link IdP proxy metadata, should your SP implementation require this for validating scoped attribute values (this is typically the case for Shibboleth SP, for example).
Use the AuthenticatingAuthority element included in the SAML response, inside the authentication statement. The value(s) are identifiers of the authentication authorities that were involved in the authentication of the user, not including the assertion issuer, and should match the entityID of the user's home IdP. Your SP implementation should support extracting this information from the response:
- Shibboleth SP (version 2.5 and above) supports this. An Assertion AttributeExtractor must be configured, so as to expose the value(s) of this element as a variable/header. Please refer to the documentation.
- SimpleSAMLphp shows how to retrieve the list of authenticating authorities from the authentication data. An Authentication Processing filter is also available, which can be used to expose this information as a session attribute.
Use the authnAuthority attribute value(s), which provides the exact same information as the AuthenticatingAuthority element; it is just easier to access, due to being included in the attribute statement rather than the AuthnStatement.