Upgrade IdP 2.0/2.1 to 2.2

When upgrading to IdP 2.2 you should make the following changes in your configuration files. None of these changes are strictly required but making these changes is necessary for some new features and to remove some warning messages.

Endorsed Libraries

Xerces, one of the two libraries that you should have endorsed when installing the IdP has a new version out. To do this, refer to the Servlet container preparation documentation referenced in the first step of the IdP installation instructions.

Logging Configuration

The latest version of the logging framework used by the IdP has changed its configuration slightly, removing some configuration options and adding additional ones.

First, you will also need to remove each <ImmediateFlush> element, as this option is no longer supported.

Next you will need to replace each <layout> element with an <encoder> element and specify the character set used in the logging messages.

So, currently, you will have sections that look like this:

<layout class="ch.qos.logback.classic.PatternLayout">
   <Pattern>SOME_PATTERN_STRING</Pattern>
</layout>

and they need to be changed to look like this:

<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
   <Pattern>SAME_PATTERN_AS_ABOVE</Pattern>
   <charset>UTF-8</charset>
</encoder>

Changes in Principal Name Returned from Authentication

It has always been the case that the authentication engine can, and usually does, return more than one identifier for a user (e.g. the uid and the DN for the user if authenticating against an LDAP). As such, the value of RequestContext.getPrincipalName() was always defined as the "first" of an unordered set. As a stop-gap solution, IdP 2.2 will now prefer the user's login ID (the thing they type in the username field of the login page) if available, if not it will fall back to the same "first" of an unordered set behavior.

However, if you need something other than the username, or the authentication mechanism you use doesn't use a username, you will need to write a custom attribute definition that access the javax.security.auth.Subject, via RequestContext.getUserSession().getSubject(), and select whichever principal name is correct for your use case.

LDAP and Relational Database Result Caching

The LDAP and Relational Database data connectors can now cache their results for a configurable period of time. To enable this you need to configure the cache manager used by the code by adding the following <bean> at the same level as the other <bean> elements in the internal.xml file.

<bean id="shibboleth.CacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean" />

Timeout/Duration/Interval Property Syntax Change

All of the configuration properties dealing with time has been changed to use the XML schema duration notation. This removes any ambiguity as to the time units (minutes, second, milliseconds) of the configuration property.

When you start the IdP it will find the various configuration properties that need to be updated to the new notation and will write out a warning message in the idp-process.log indicating where the configuration options are and what the current value would be in duration notation. Then simply edit that file, locate the configuration option, and replace the current value with the one given by the IdP.

MDC Cleanup Filter

The IdP currently does not clean up a small piece of state when it finishes a request. This state is associated with something known as the Mapped Diagnostic Context (MDC) of the logging framework. If you maintain your own web.xml file with which you replace the shipped with version, be sure to add the following after the <listener> element.

<!--  Add IdP SLF4J MDC cleanup filter to all requests -->
<filter>
   <filter-name>SL4JCleanupFilter</filter-name>
   <filter-class>edu.internet2.middleware.shibboleth.common.log.SLF4JMDCCleanupFilter</filter-class>
</filter>
<filter-mapping>
   <filter-name>SL4JCleanupFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>

Clustering

Grab the latest tc-config.xml from the clustering documentation.