Upgrading Shibboleth 4.3 & Jetty9 to Shibboleth 5.0 and Jetty11 (recommended)

Upgrading Shibboleth 4.3 & Jetty9 to Shibboleth 5.0 and Jetty11

Upgrading Shibboleth 4.3 & Jetty9 to Shibboleth 5.0 and Jetty11 (recommended) 

This guide works off of the Guide that set up Shibboleth 4.3 with Jetty9 from idem-community. 
Shoutout to their GitHub page and that guide --- HOWTO Install and Configure a Shibboleth IdP v4.x on Debian-Ubuntu Linux with Apache2 + Jetty9 
LINK --- https://github.com/ConsortiumGARR/idem-tutorials/blob/master/idem-fedops/HOWTO-Shibboleth/Identity%20Provider/Debian-Ubuntu/HOWTO%20Install%20and%20Configure%20a%20Shibboleth%20IdP%20v4.x%20on%20Debian-Ubuntu%20Linux%20with%20Apache2%20%2B%20Jetty9.md 

I am no expert but I have been working diligently with this system and would like to contribute to the open source community that uses Shibboleth. Take this process with a grain of salt, I am sharing this process because it worked for me. 


The documentation for Shibboleth recommends upgrading Jetty to version 10, followed by upgrading Shibboleth to version 5 and Java to version 17. My experience with upgrading Jetty9 to Jetty 10 has some issues with the packages and the renaming of Java to Jakarta. When I was testing I had success launching Jetty 11 directly from 9. 

From here, based on dependencies we found a successful order of upgrades. 
1. Upgrade Java to Java Amazon Corretto 17 
2. Update any plugins as much as possible before your upgrade 
3. Upgrade Shibboleth from IdP 4.3 to Shibboleth 5.0 
4. Upgrade Jetty 9.4 to Jetty 11.0 
5. Fix any Shibboleth-specific issues in the configuration field to enable Shibboleth functionality. 



1. Upgrade Java to a usable version for Shibboleth 5. 
A. From a fresh install: 
    wget -O- https://apt.corretto.aws/corretto.key | apt-key add -

    apt-get install software-properties-common

    add-apt-repository 'deb https://apt.corretto.aws stable main'

    apt-get update; apt-get install -y java-17-amazon-corretto-jdk

    java -version

Check that Java is working:
    update-alternatives --config java
    (It will return something like this "There is only one alternative in link group java (providing /usr/bin/java):" )

B. From a previously installed java 
	sudo apt update 
	sudo apt install -y java-17-amazon-corretto-jdk
	java -version 
    (This should return the new version of java, but we will remove the old version to ensure it will not revert on us in some weird scenario.) 
    sudo apt remove java-11-amazon-corretto-jdk 
    update-alternatives --config java 
    (Now this should only return one alternative which is version 17; if you run this before you do the apt remove, you will see three options 1-auto 2-manual java 11 3-manual java 17) 



2. Add and update your plugins - typical use if using DUO as two to have a plugin dependency 
Make sure you install a new plugin that supports the default scripting language. When you upgrade your Java version to Java 17 it no longer comes with a default scripting language. 

This largely impacted the scripted attributes in the attribute resolver. Java 11 comes with a default scripting language. To support javascripts used in the attribute resolver or other configurations using Java script install one of the scripting language plugins. Nashorn is recommended. 

	Check this link for the information about the default scripting language: (Document)
	Check this link for information about the Nashorn Plugin we will be using: (Nashorn)

	cd /opt/shibboleth-idp/bin
	sudo ./plugin.sh -I net.shibboleth.idp.plugin.nashorn


Note: In my process, I forgot this step and did this last, the issue with forgetting to update the rest of your plugins is there will be issues starting your IDP which can be fixed by updating the plugins. If you forget you will get a warning when installing/upgrading Shibboleth 

    cd /opt/shibboleth/bin
    sudo ./plugin.sh -fl (list what plugins you have active) 

Example output 
Plugin: net.shibboleth.idp.plugin.authn.duo.nimbus	Current Version: 2.0.0
	Versions 
	1.0.0:	Min=4.1.0	Max=4.1.1	Support level: OutOfDate
	1.1.0:	Min=4.1.1	Max=4.2.0	Support level: OutOfDate
	1.1.1:	Min=4.1.1	Max=4.2.0	Support level: OutOfDate
	1.2.0:	Min=4.2.0	Max=4.3.0	Support level: OutOfDate
	1.3.0:	Min=4.2.0	Max=5.0.0	Support level: OutOfDate
	1.4.0:	Min=4.3.0	Max=5.0.0	Support level: OutOfDate
	1.4.1:	Min=4.3.0	Max=5.0.0	Support level: Current
	2.0.0:	Min=5.0.0	Max=6.0.0	Support level: Current

Plugin: net.shibboleth.oidc.common	Current Version: 3.0.0
	Versions 
	1.0.0:	Min=4.1.0	Max=5.0.0	Support level: OutOfDate
	1.1.0:	Min=4.1.0	Max=4.2.0	Support level: OutOfDate
	2.0.0:	Min=4.2.0	Max=5.0.0	Support level: OutOfDate
	2.1.0:	Min=4.2.0	Max=5.0.0	Support level: OutOfDate
	2.2.0:	Min=4.3.0	Max=5.0.0	Support level: OutOfDate
	2.2.1:	Min=4.3.0	Max=5.0.0	Support level: Current
	3.0.0:	Min=5.0.0	Max=6.0.0	Support level: Current

From here you can update your used plugins with 
    sudo ./plugin.sh -u <id> 
These examples would then be 
	sudo ./plugin.sh -u net.shibboleth.idp.plugin.authn.duo.nimbus 
	sudo ./plugin.sh -u net.shibboleth.idp.oidc.common 



3. Upgrade Shibboleth Idp 4.3 to Shibboleth IdP 5 (In Place Upgrade)
	1. Get the new download to a folder outside the IDP scope 
	cd /usr/local/src
    sudo wget http://shibboleth.net/downloads/identity-provider/latest5/shibboleth-identity-provider-5.0.0.tar.gz

2. Un-tar the file 
    sudo tar -xzf shibboleth-identity-provider-5.0.0.tar.gz 

3. Run the installer from the new provider outside the scope 
    cd shibboleth-identity-provider-5.0.0/bin
    sudo ./install.sh
    (if you run into an error with the java home variable check this path to ensure the java has been updated --                /etc/environment) 

4. Rebuild the war file in the IDP scope directory 
    cd /opt/shibboleth-idp/bin
    sudo ./build.sh



4. Install Jetty 11 - Note: until this is done shibboleth will not be able to run. 
Note: this will assume you have shibboleth configured to work as defined in the IDEM guide, you will be upgrading the jetty in place with the configurations made beforehand. 
	
    A. change back to your source folder and get the new Jetty 11 version 
	cd /usr/local/src
    sudo wget https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-home/11.0.16/jetty-home-11.0.16.tar.gz
    sudo tar xzvf jetty-home-11.0.16.tar.gz

    B. Update the Sym Link for the jetty Home distribution 
    sudo ln -nsf jetty-home-11.0.16 jetty-src 
    sudo chown -R jetty:jetty jetty-src jetty-home-11.0.16 

    C. Update the idp.xml file in the webapps folder to be able to read the Shibboleth application's war file 
    cd /opt/jetty/webapps
    sudo vim idp.xml (this file update can be found in the upgrade documentation) 

		<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="war">/opt/shibboleth-idp/war/idp.war</Set>
  <Set name="contextPath">/idp</Set>
  <Set name="extractWAR">false</Set>
  <Set name="copyWebDir">false</Set>
  <Set name="copyWebInf">true</Set>
  <Set name="persistTempDirectory">false</Set>
</Configure>
	
    D. Reload the daemon and restart Jetty to apply the changes 
	sudo systemctl daemon-reload 
	sudo systemctl restart jetty.service 

    E. Check the Jetty status 
	systemctl status jetty.service 



5. Check your configuration for issues. 
Helpful Tip for searching for depreciations: 
Use the grep command to search for properties that are deprecated from settings or are removed. The syntax is as follows:
    cd /opt/shibboleth-idp 
	grep -nr <string> . 
-nr is for showing the line number where the string was found (the n) and r is to recursively search your folders. The . after the string tells grep which directory to search for recursively through. 



Example Depreciations I worked though. 
1. WARN [DEPRECATED:113] - property 'idp.authn.Duo.supportedPrincipals' is no longer supported
Comment this out in the two duo configuration files that are relied on. Note: even the newest IDP-500 files that come installed with the new syntax as extra files do not respond to this error when I went through the update. 
	cd /opt/shibboleth-idp/conf/authn
	sudo vim duo-oidc.properties   
	sudo vim authn.properties
	- you want to look for the following line and add comments to remove the depreciation 
#idp.authn.Duo.supportedPrincipals = \
#    saml2/http://example.org/ac/classes/mfa, \
#    saml1/http://example.org/ac/classes/mfa

2. WARN [DEPRECATED:113] - property 'idp.httpclient.filecaching.cacheDirectory' is no longer supported
This setting was found in the services.properties. Commenting the line with the property removes the depreciation. 

3. Depreciation xxx - replaced by parent "shibboleth.BasicX509CredentialFactoryBean"
Issues in the Keys for Keys in the 'credentials.xml' file. I missed the first part of this error but its an issue with the way my keys were defined in the credentials file. I fixed this by checking the credentials.xml.idp-500 file for the syntax changes and reflecting that in the default file location. 

 <util:list id="shibboleth.DefaultEncryptionCredentials">
        <bean parent="shibboleth.BasicX509CredentialFactoryBean"
            p:privateKeyResource="%{idp.encryption.key}"
            p:certificateResource="%{idp.encryption.cert}"
            p:entityId-ref="entityID" />