Shibboleth IdPv3: Considerations in the Context of SWITCHaai

This page documents considerations and recommendations regarding the deployment of the Shibboleth IdPv3 in the SWITCHaai federation and on migration from existing Shibboleth IdPv2 installations.

Table of Contents

  1. Introduction
  2. Suggested Approach for Migrating from a Shibboleth IdPv2.x
  3. Deployment Decisions
  4. IdP Single Logout Support
  5. Clustering, Load Balancing, High Availability

1. Introduction

The third-generation Shibboleth Identity Provider software IdPv3 is the result of more than two years of active development. It's a substantial redesign and includes a large number of new features along with a modernized architecture based on Spring Web Flow.

2. Suggested Approach for Migrating from a Shibboleth IdPv2.x

Note: Do not consider an in-place upgrade from a Shibboleth IdPv2 to IdPv3, it would be too risky!

If you are responsible for an IdPv2 in the SWITCHaai federation follow these three steps:

  1. Install IdPv3 on a completely new instance (physical or virtual) according to the Shibboleth Identity Provider 3 Installation Guide.
  2. Use the upgrade instructions integrated into the installation guide to derive from the current IdPv2 configuration settings the corresponding new settings for IdPv3.
  3. Only after thorough tests replace the current IdPv2 instance with the new IdPv3 instance.

The current IdP entityID must be retained as well as all the stored persistentIDs! However, the uApprove modules 'terms of use' and 'attribute release' settings cannot be migrated due to the complete redesign in IdPv3. Users will have to consent again for terms of use and attribute release. Consult the dedicated Shibboleth IdPv3 User Consent Configuration Guide to learn how to tailor its configuration for your needs.

3. Deployment Decisions

For the deployment of Shibboleth IdPv3 in the SWITCHaai federation, SWITCH has taken the decisions listed below prior to writing the guide.

SWITCH commits to provide SWITCHaai participants support for IdPv3 installations running on the recommended operating systems and using the recommended software and versions, which can differ from those of the Shibboleth project in some cases. SWITCH cannot commit to provide support for other operating systems, software and versions.

3.1 Operating Systems: Linux long-term support

An increasing number of services rely on the security and reliability of the Identity Provider. An enterprise-grade operating system with long-term support provides a stable basis that does not require e.g. yearly operating system upgrades or upgrades of th IdPs crucial foundation like the Java Runtime Environment, servlet container or HTTP server. The IdP guide covers installation on Ubuntu Server 14.04 LTS and Red Hat Enterprise Linux 7 / CentOS 7.

3.2 Java & Servlet Container: OpenJDK 7, Apache Tomcat 7 & Apache HTTP Server 2.4

SWITCH decided to recommend and document the use of OpenJDK 7. It is a standard package in the supported Linux long-term distributions and gets security updates. The experience gained with OpenJDK and IdPv2 was positive enough to support this decision.
The Shibboleth Project recommends Oracle "standard" JVM instead of OpenJDK, but Oracle JVM is no standard package on the above-mentioned operating systems. Therefore, it is less likely to be kept up-to-date.

The IdPv3 requires Java 7 or newer. SWITCH decided to recommend and document the use Java 7. Java 8 is not (yet) the default Java version on Linux long-term distributions. In addition, Java 8 introduced a new scripting engine (code name 'Nashorn') that is not backwards compatible to the one in Java 7 (code name 'Rhino'). The IdP uses the Java scripting engine for some attribute definitions in the attribute-resolver.xml file. Not much experience exists with 'Nashorn'. Therefore, it is safer to continue to use 'Rhino' and postpone the update to 'Nashorn' to a future upgrade.

The setup used for IdPv2 included an Apache web server that was running in front of a Tomcat servlet container. In our experience, this has been a stable and reliable setup for operating the Identity Provider. Therefore, SWITCH recommends and documents the use of Apache Tomcat 7 together with Apache HTTP Server 2.4 for running the Identity Provider.

3.3 SWITCHaai specific IdP-install.sh wrapper and conf/credentials.properties

Running the install.sh script included in the IdP distribution without any parameters would create a default configuration which is not very suitable for an IdP in the SWITCHaai federation. A simple SWITCHaai specific idp-install.sh wrapper script ensures that the basic configuration parameters are set to SWITCHaai compatible defaults.

The wrapper creates this central credential store /opt/shibboleth-idp/conf/credentials.properties. It stores items like the idp.sealer.password, the idp.persistentId.salt or the credentials required to verify the user-authentication or retrieve the attributes from the user directory. Without this central credential store, all these credentials would be distributed across various configuration files.

3.4 Database for persistentIDs and user consent: PostgreSQL

A major change for IdPv3 is our recommendation for the database product to use for persistentIDs and user consent settings. SWITCH recommends and documents to use PostgreSQL. It has a long track record as open source DB implementation with emphasis on SQL standards-compliance.
In the past SWITCH documented the use of MySQL. Since Oracle acquired MySQL, security patches for MySQL are no longer provided separately, but only as part of Oracle's huge 'Critical Patch Update' bundles. This impedes selective back-porting of security patches that is essential for long-term distributions.

SWITCH will provide instructions on how to retain the persistentIDs from a current MySQL DB.

Unlike the Shibboleth project, SWITCH recommends and documents to continue to store all user consent decisions in a database. That way, the user consent decision is stored independent from the web browser and device. The user has to consent only once, which improves the user experience.

3.5 IdP Session Storage: Client Session Storage with Cookies

An IdP administrator has four IdPv3 storage options to store client session details. SWITCH recommends and documents the client session storage based on secured cookies in the browser. This is also the default configuration recommended by the Shibboleth project. It easily supports clustering (see below chapter 5) without the need to introduce a server-side storage synchronized between clustering nodes. However, as drawback, single logout support is not possible (details below chapter 4).

3.6 Attribute resolution configuration: Split in Multiple Files

SWITCH no longer provides a single, very long attribute-resolver.xml file but decided to provide three parts. Two for the core attributes: One to be compatible with SWITCHaai and one for compliance with interfederation. The third file, attribute-resolver-other.xml, contains all other attributes from the attribute specification. Mostly an IdP supports only a subset of all the defined attributes. All these files need to be manually custom tailored to fit the source and format of how the attributes are available in the local directory.

If the IdP should also support some locally or bilaterally defined attributes, we suggest putting them into a separate attribute-resolver-local.xml file.

3.7 Login Form & Error Templates:

For the login and error pages in IdPv3, the Shibboleth project moved away from previously used .jsp to .vm template files, interpreted by the Java-based Velocity template engine. SWITCH provides new login and error templates. They were derived from the templates created for IdPv2 but they also include the features the Shibboleth project provides now in their default template files.

4. IdP Single Logout Support

The single logout support available in IdPv3.1.x is as limited as it was in IdPv2.4.x. The client session at the IdP can be terminated, but not the sessions at the SPs, except on the SP that initiated the single logout. A full implementation of IdP single logout is included in IdPv3.2 released in November 2015. To deploy the SLO feature as available in version 3.1 of the IdP, the IdP needs server-side session storage.

Once the full logout is documented by the Shibboleth project, SWITCH will provide additional information on how to configure an IdP to support proper single logout.

5. Clustering, Load Balancing, High Availability

The Shibboleth project documents clustering the IdP in its wiki. It is strongly recommended to read that page before designing the IdP setup.

For an IdP in the SWITCHaai federation, clustering continues to require server-side storage, as the persistent IDs need to be stored in a relational database. With only persistentIDs and user consent decisions there are relatively few writes and more frequent reads. Many more write operations would occur when also client sessions would be stored in the database instead of in cookies.

SWITCH does not yet recommend any specific clustering approach due to lack of own experience. However, SWITCH documented on the Shibboleth Identity Provider 3 Clustering page what we know. Let us know of your experience in this field!