Deprecated features in Shibboleth IdP v3 will be removed in v4

Last Update: 2020-10-02

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.

Binary attributes

If your current IdP attribute resolver uses attributes from the LDAP user directory which are interpreted in a binary way then you will need to update your configuration during the upgrade to ensure they continue to be interpreted in the same way (and therefore produce the same results). This is because the underlying LDAP libraries have changed.

More details are available in the Release Notes.

Checking if you're affected

To check if you need to make any changes, examine your attribute-resolver.xml file for <LDAPProperty> elements defining a java.naming.ldap.attributes.binary value which will probably look like: 

 <LDAPProperty name="java.naming.ldap.attributes.binary" value="objectSid"/>

You may have none, one or many of these. If you have none then no action is required. If you have any then you'll need to transform them into the new format for this configuration which is available in v3.4.5 or later.

Required changes

Remove all the relevant <LDAPProperty ...> elements and replace them with a single <BinaryAttributes> element with a space-separated list of attributes.

Before

 <LDAPProperty name="java.naming.ldap.attributes.binary" value="objectSid"/>
 <LDAPProperty name="java.naming.ldap.attributes.binary" value="objectGUID"/>
 <LDAPProperty name="java.naming.ldap.attributes.binary" value="thumbnailPhoto"/>

After

 <BinaryAttributes>
     objectSid
     objectGUID
     thumbnailPhoto
 </BinaryAttributes>

Checking binary attribute if used for eduPersonTargetedId

Assuming that you're using the binary attribute to generate eduPersonTargetedId, you should carry out the following procedure:

1. Check the generated eduPersonTargetedId value for a known user 

 # cd /opt/shibboleth-idp
 # ./bin/aacli.sh -r https://test.ukfederation.org.uk/entity -n TESTUSER | grep -A 2 eduPersonTargetedID
      "name": "eduPersonTargetedID",
      "values": [
            "KOMX3NCHDRLZKEOCYVYIVKV36LJIMFFL"

2. Update the configuration and reload the attribute resolver or restart the service 

 # ./bin/reload-service.sh -id shibboleth.AttributeResolverService
 Configuration reloaded for 'shibboleth.AttributeResolverService'

3. Recheck the same user and confirm the value has not changed 

 # ./bin/aacli.sh -r https://test.ukfederation.org.uk/entity -n TESTUSER | grep -A 2 eduPersonTargetedID
      "name": "eduPersonTargetedID",
      "values": [
            "KOMX3NCHDRLZKEOCYVYIVKV36LJIMFFL"

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.