Child pages
  • Upgrading a 3.x IdP to 4.x

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


The IdP plugin module that generates the auEduPersonSharedToken attribute also has to be upgraded - the version released earlier for IdP 3.4.x is not compatible with IdP 4.x.  A new version, 2.0.x (2.0.2 3 as of December 7thFebruary 3rd, 20202021), has been released for IdP 4.x.


The new version can be downloaded from

The new version also introduces syntax changes in how it is configured - the single but significant change is replacing the custom DatabaseConnection element with a reference to a DataSource defined in other parts of the IdP configuration.


  • Get the new version:

    Code Block
    cd /root/inst
    tar xzf shibboleth-identity-provider-${NEW_IDP_VERSION}.tar.gz
    cd shibboleth-identity-provider-${NEW_IDP_VERSION}

  • Start the upgrade: stop Tomcat:

    Code Block
    service tomcat stop

  • Run the installer (with the correct JDK) - and also fix permissions right after running the installer:

    Code Block
    JAVA_HOME=/usr/lib/jvm/java-11-openjdk ./bin/
    chown -R tomcat.tomcat /opt/shibboleth-idp/
    # and for SELinux:
    restorecon -R /opt/shibboleth-idp

  • Update LDAP connector definition.  Besides the settings deprecated in IdP 3.x and removed in IdP 4.x, there are also settings deprecated in IdP 4.x to be removed in a future version (possibly 5.x).  Now is a good time to make the changes and have the IdP running without any deprecation warnings.  In /opt/shibboleth-idp/conf/attribute-resolver.xml , make the following changes:
    • Check the ConnectionPool element inside the LDAPDirectory DataConnector element - and remove any failFastInitialize attribute it might have.
    • Check the LDAPDirectory DataConnector element for any LDAPProperty elements.  These elements have been deprecated without a generic replacement, but some specific properties can be mapped to LDAPDirectory element attributes.  See the LDAPDirectory element documentation for further information.
      • Replace java.naming.ldap.attributes.binary property with the BinaryAttributes element, with the space-delimited list of LDAP attribute names as the text inside the element - e.g.:

        Code Block
        <BinaryAttributes>object GUID objectSid<BinaryAttributes/>

      • Remove/comment-out <LDAPProperty name="java.naming.referral" value="follow"/> .  This property can be replaced with the boolean attribute followReferrals on the LDAPDirectory element.  However, this property was only needed with IdP software up to and including 2.x - and has been ignored by IdP 3.x and 4.x.
        Actually turning the referral following on might have undesired side-effects (IdP attempting to connect to other trees in the AD forest, potentially failing - and reporting a warning) - unless it is needed for the IdP operation, we recommend leaving it off.

        titleClick here to expand the instructions to turn followReferrals on...

        Code Block
        <DataConnector id="myLDAP" xsi:type="LDAPDirectory"

  • Upgrade SharedToken module:
    • Download new version:

      No Format
      wget -P /opt/shibboleth-idp/edit-webapp/WEB-INF/lib

    • Remove old version(s):

      No Format
      rm /opt/shibboleth-idp/edit-webapp/WEB-INF/lib/arcs-shibext-1.*.jar

    • Update definition: in /opt/shibboleth-idp/conf/attribute-resolver.xml , locate the SharedToken DataConnector and replace the DatabaseConnection element with a DataConnector attribute databaseConnectionID referening to a DataSource defined in /opt/shibboleth-idp/conf/global.xml (as part of the IdP 3.x installation Database Storage setup).  So assuming the DataSource is named shibboleth.JPAStorageService.DataSource , this would be:

      Code Block
      <DataConnector xsi:type="st:SharedToken" xmlns:st=""

  • Rebuild IdP WAR file (with new sharedToken module version) and start Tomcat

    Code Block
    service tomcat start

  • The updated version of the IdP should be running
  • To properly record the change, edit /etc/profile.d/ and update IDP_VERSION to the new IdP version.