Deprecated features in Shibboleth IdP v3 will be removed in v4

This short guide covers the most commonly used features, it is important that you also manually review your configuration files and the documentation available on the Shibboleth Wiki. This is particularly important if you are using other features not mentioned here.

This is guidance for Shibboleth IdP operators who have upgraded to IdP v3.4 from an earlier version. It is intended to ready them for an upgrade to IdP v4 once it has been released.

The Shibboleth team have deprecated elements in the IdP configuration files which they will remove in v4. They have provided alternative configuration elements in v3.4 to replace the deprecated elements. This is to simplify the configuration files and to ensure that v4 is an extensible platform.

Please note that every Shibboleth IdP deployment up to and including v3.3.3 uses elements that have been deprecated and every Shibboleth IdP deployer MUST make changes to their configurations. In many cases, the configuration changes will be straightforward to make. You MUST upgrade to v3.4.x before making the changes.

General procedure for dealing with deprecated elements

The Shibboleth team have added functions to log a WARN message when a deprecated element is used for the first time. This means the general procedure for addressing the deprecated elements in v3.4 is:

  • Restart the Java web servlet container (Jetty or Tomcat)
  • Authenticate against a test site
  • Check the idp-warn.log or idp-process.log for any deprecation warnings
  • Re-configure the IdP to use the new configuration elements
  • Restart the web servlet container and ensure that the warnings have gone

Dependency and sourceAttributeID in Attribute Resolution

You must update all AttributeDefinition elements which have a sourceAttributeID="" attribute and which include a <Dependency ref="" /> element.

Where the dependency is a DataConnector, the Dependency element is replaced with an InputDataConnector element, and adding in the attributeNames="" attribute, removing sourceAttributeID="" from the <AttributeDefinition. For example,

    <AttributeDefinition id="eduPersonPrincipalName" xsi:type="Scoped" sourceAttributeID="uid"
      scope="%{idp.scope}">
        <Dependency ref="myLDAP" />

becomes

    <AttributeDefinition id="eduPersonPrincipalName" xsi:type="Scoped" scope="%{idp.scope}">
        <InputDataConnector ref="myLDAP" attributeNames="uid" />

Where the dependency is a different AttributeDefinition, then you replace the Dependency element with an <InputAttributeDefinition ref="" /> and remove the sourceAttributeID="" from the AttributeDefinition. For example,

    <AttributeDefinition id="eduPersonScopedAffiliation" xsi:type="Scoped" sourceAttributeID="affiliation"
      scope="%{idp.scope}">
        <Dependency ref="eduPersonAffiliation" />

becomes

    <AttributeDefinition id="eduPersonScopedAffiliation" xsi:type="Scoped" scope="%{idp.scope}">
        <InputAttributeDefinition ref="eduPersonAffiliation" />

You are encouraged to also review the Shibboleth IdP v3 documentation on the deprecation of the dependency attribute

Deprecated Namespaces

For IdP operators who upgraded from Shibboleth v2 or from versions of Shibboleth IdP prior to v3.3, the attribute-resolver.xml and attribute-filter.xml files could also be using deprecated XML namespaces.

For example if you see <resolver:AttributeDefinition in attribute-resolver.xml or <afp:AttributeFilterPolicy in attribute-filter.xml, then these are using the deprecated namespaces.

There is a section on deprecated namespaces within the Shibboleth IdP v4 deprecation documentation , as well as details on the Attribute Resolver Configuration Documentation and the Attribute Filter Configuration

The continued support for this is part of the Shibboleth IdP IdP V2 Compatibility, which will be removed in Shibboleth IdP v4.

Other areas to be aware of

The V2 compatibility layer is now deprecated. You may be using this in Scripted Attribute definitions. Or you may have (uid=$requestContext.principalName) in your attribute-resolver.xml or ldap.properties file, and it should be replaced by (uid=$resolutionContext.principal).

Review the deprecated IdPv4 documentation

The above is not an exhaustive list, we have listed what we believe to be the most common configuration items for Shibboleth IdP operators operating in the UK federation. We advise that all Shibboleth IdP operators review the the Shibboleth documentation on Deprecation in IdP v4.0, review their logs for deprecation warnings, manually review the configuration files, and build a comprehensive test plan to exercise all configuration elements.