Installation and configuration of Shibboleth IdP v3 software for HKAF

Last update 9 March 2017

The page is maintained by the HKAF support team, and contains some advice and pointers to the Shibboleth project documentation, and some HKAF-specific configuration information. Please contact the HKAF helpdesk for further query. If you are interested in deploying the v3 IdP, you may start at the Shibboleth IdP v3 main page, and read the system requirements and release notes.

· Shibboleth IdP v3 deployment

· HKAF metadata configuration

· Configuration

· Registering your Shibboleth v3 IdP

· Testing new IdP deployments

Shibboleth IdP v3 depolyment

The Shibboleth IdP v3 system requirements page notes that the only supported servlet containers are Tomcat 8, Jetty 9.2 and Jetty 9.3, and that the recommended servlet container is Jetty. These servlet containers can all act as standalone web servers.

For a new IdP deployment, you should first read the Installation page.

For a new Windows deployment, you may use the Windows installer, but please read the main Installation page before moving to the Windows installation page.

Linux users deploying from scratch will need to determine whether to use the Tomcat or the Jetty container and follow the appropriate links in the "Non-Windows Installation" section of the Installation page to set up their chosen container and install the software:

Configuration

General guidance

Typically the IdP installation directory is /opt/shibboleth-idp on Linux, or C:\Program Files\Shibboleth\IdP or C:\Program Files (x86)\Shibboleth\IdP on Windows. The installation directory may be referred to in configuration files as %{idp.home}, and we refer to it as such here. Configuration files are located in the conf subdirectory of the IdP installation directory, ie. %{idp.home}/conf.

Take configuration a step at a time; work on a particular configuration task, and test and modify your configuration until you have achieved the desired result. Check the idp-process.log and the container logs. Generally we suggest the following order:

· Turn logging up to DEBUG level for the duration of the configuration tasks

· Perform user login, configuration usually in ldap.properties or jaas.config

· Configure federation metadata

· Determine attribute release in attribute-filter.xml and attribute-resolver.xml

· increase memory

· customise login page, configuration in views/login.vm, views/login-error.vm, messages/error-messages.properties

· perform any tasks required for going into production

Attribute release

HKAF supports the release of a set of attributes based on the eduPerson entity class. Participant IdPs of HKAF will release seven “core” and three “optional” attributes to SPs for access control or personalization or other purposes. The following table describes the attribute set supported by HKAF.

Core Attributes	Description	Example Value	Multi-Value
eduPersonAffiliation	Specifies the person’s relationship(s) to the institution in broad categories such as student, faculty, staff, alum, etc.	faculty	Y
eduPersonScopedAffiliation	Specifies the person’s affiliation within a particular security domain in broad categories such as student, faculty, staff, alum, etc.	faculty@ust.hk	Y
eduPersonTargetedID	A persistent, non-reassigned, privacy-preserving identifier for a user shared between an identity provider and service provider. An identity provider uses the appropriate value of this attribute when communicating with a particular service provider or group of service providers, and does not reveal that value to any other service provider except in limited circumstances.	https://idp.ust.hk /idp/shibboleth!ht tps://sp.ust.hk/shi bboleth!cmWc3m KualJlxjAwfFdu2 mVgRxw=	N
eduPersonPrincipalName	EPPN is eduPerson equivalent of a username within the organization’s security domain	peterchan@ust.hk	N
displayName	Preferred name of a person to be used when displaying entries	Peter Chan	N
cn	An individual's common name, typically the official full name	Peter Tai Man Chan	Y
mail	Email address, single value. User’s preferred outward facing email address with regard to the organization	peterchan@ust.hk	N

Optional Attributes	Description	Example Value	Multi-Value
givenName	A person’s first name or preferred name	Peter Tai Man	Y
sn (surname)	A person’s surname	Chan	Y
schacHomeOrganization	Specifies a person’s home organization using the domain name of the organization - AAF and eduGAIN recommended attribute	ust.hk	N

Attribute filter

The attribute filter configuration determines which attributes are released to which service providers, and is configured in the conf/attribute-filter.xml file. The following configuration snippet would release two attributes, namely eduPersonScopedAffiliation and eduPersonTargetedID, to any SP with which the IdP successfully authenticated. Note that the SP might be a HKAF SP, or an SP imported from another federation via eduGAIN interfederation, or another SP for which the IdP has the metadata configured one way or another. More sophisticated attribute filters are possible; please see the Shibboleth documentation.

</AttributeRule>

</AttributeRule>

</AttributeRule>

</AttributeFilterPolicy>

Attribute resolver

The attribute resolver configuration specifies how attributes are retrieved or generated on behalf of your users. You need to make sure that there is a resolver:DataConnector element set up in the file to connect to your LDAP, assuming the attributes for your users are stored in an LDAP, or attributes or groups from the LDAP can be used to generate attributes.

An example of the two configuration files: Attribute-resolver.xml and Attribute-resolver-ldap.xml.

Note that the attribute-resolver.xml file in the conf directory contains an example LDAP resolver:DataConnector configuration, called attribute-resolver-ldap.xml. The resolver:DataConnector configuration will need to be modified for your local set-up.

Also note that if the LDAP has not been populated with the required attribute e.g., eduPersonAffiliation and it is not possible to arrange for it to be populated then you may need to script an attribute definition for the attribute eduPersonAffiliation, based on other attributes or groups in the LDAP.

HKAF metadata configuration

Metadata URL and metadata signing certificate

The HKAF metadata is required for the IdP to validate HKAF service providers (SPs), and for the SPs to validate IdPs. It contains SAML metadata for all registered HKAF IdP and SP deployments. The production HKAF metadata is available at this URL:

https://md.hkaf.edu.hk/hkaf-metadata.xml. Metadata documents are preferably accessed using the https request, though accessible via http.

To secure against compromise, the HKAF metadata is signed using the HKAF's private key. Subscriber MUST use the public key available at https://md.hkaf.edu.hk/hkaf-metadata-certificate.pem to verify the metadata document whenever it is retrieved.

The certificate is required in the IdP configuration so that it can be used to verify the signature on the HKAF metadata. It needs to be downloaded and saved to the %{idp.home/credentials} directory.

To confirm that you have obtained the correct key ensure the file you have downloaded conforms to the following:

$> openssl x509 -subject -dates -fingerprint -in hkaf-metadata-certificate.pem

subject= /O=Hong Kong Access Federation/CN=HKAF Metadata

notBefore=Jun 2 07:01:40 2016 GMT

notAfter=Jun 2 07:01:40 2017 GMT

SHA1 Fingerprint=84:D9:CB:19:61:FA:78:C3:4C:CC:BF:4B:62:46:47:66:2E:3D:E0:FF

Configuration in metadata-providers.xml

After you have downloaded the HKAF signing certificate and verified its authenticity as described above, you configure the IdP to use the HKAF metadata by editing %{idp.home}/conf/metadata-providers.xml and adding the following MetadataProvider element.

<MetadataProvider xsi:type="FileBackedHTTPMetadataProvider" id="FederationMetadata"

metadataURL="{{ metadata_url }}"

backingFile="{{ shib_idp.home }}/metadata/federation-metadata.xml"

httpCaching="memory" maxRefreshDelay="PT2H" refreshDelayFactor="0.125">

<MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"

certificateFile="{{ shib_idp.home }}/credentials/federation-metadata-cert.pem">

</MetadataFilter>

<RetainedRole>md:SPSSODescriptor</RetainedRole>

</MetadataFilter>

</MetadataProvider>

Other configuration

Please see the Shibboleth project configuration documentation.

Registering your Shibboleth v3 IdP

See the HKAF v3 IdP registration pages.

Testing new IdP deployments

Once you have registered your IdP, you can test your IdP configuration using this HKAF test service provider:

https://test.hkaf.edu.hk