Commencing migration towards the checked flag OpenSAML 3

6 min readOct 11, 2019

Why migrate when it works just fine?

Before climbing uphill, let’s take a peek into the purpose of migrating from OpenSAML 2 to OpenSAML 3.

Doesn’t matter if it works fine. Still, you’ll need to migrate

Referring to the official website you can see that OpenSAML 2 has reached its end of life on 31/07/ 2016 for Java and 17/07/2018 for C++. This means that the developers won’t support any of the maintenance or security updates based on OpenSAML 2. So, you are currently on your own if something goes wrong with OpenSAML 2. Due to the mentioned fact, the best option you have is to migrate to OpenSAML 3.

This blog would be a start off guide for the Java developers which provides the knowledge required to start the conversion. And if you are a C++ developer don’t lose hope the content might be related to you all as well.

Alright, Let’s kick off by looking at the difficulties that you might face during the conversion,

Roadblocks

OpenSAML 2

Since most of the dependencies are changed there is a chance that collisions could occur between OpenSAML 2 and OpenSAML 3 dependencies.

For example, there is a dependency:

<dependency>
    <groupId>org.opensaml</groupId>
    <artifactId>xmltooling</artifactId>
    <version>1.4.4</version>
</dependency>

in OpenSAML 2 but in OpenSAML 3 there is no xmltooling dependency. If you have the above dependency with OpenSAML 3 dependencies then there is a high possibility that you might get a ClassCastException just like:

Caused by: java.lang.ClassCastException: org.opensaml.xml.schema.impl.XSAnyBuilder cannot be cast to org.opensaml.core.xml.XMLObjectBuilder

so, be mindful about the dependency changes that can present during the conversion.

Resources

Resources based on the conversion are sparse to find and the available resources would not be sufficient enough to get a good understanding of what’s happening. Some of the useful resources for the conversion will be shared with you in the section “Useful Resources”. Use these resources to clarify any of your doubts regarding the conversion.

OSGi

In addition to the above, if your using OSGi then this would be a disaster because OpenSAML 3 does not support OSGi by default. You’ll get a lot of errors, and sometimes it might take a while for you to fix them. I’ll guide you through one of the first errors that you might get, below:

org.opensaml.core.xml.config.XMLConfigurationException: Resource not found

When you make your first Google search itself you’ll get the answer for this, but let me brief about why this error has occurred.

The error above occurs because the OpenSAML 3 initialization process has not been successful and various factors could be a cause for this.

Missing important dependencies that are needed for the initialization process.

The solution for this would be appending the missing dependencies onto the pom file.

The initialization process of OpenSAML 3 is not been called.

The remedy lies in calling the method:InitializationService.initialize();

The class loader is unable to find the specific classes and resources required.

This solution is a bit complex and would be a cause for more errors but, I have not found a better solution as of time being. Going into the process flow, first, you should get the current thread and then store the current class loader into a variable. Then, change the class loader to the required loader and perform the action required. Finally, set the context class loader back to the old loader.

Thread thread = Thread.currentThread();
ClassLoader loader = thread.getContextClassLoader();
thread.setContextClassLoader(InitializationService.class.getClassLoader());try {
   InitializationService.initialize();
} finally {
   thread.setContextClassLoader(loader);
}

Let’s just free aside from the blockers and see what has changed from OpenSAML 2,

Changes from OpenSAML 2 to OpenSAML 3

There’s gonna be a few changes around here

The major changes from OpenSAML 2 to OpenSAML 3 include:

The structure of the OpenSAML dependencies has changed between version 2 and 3. OpenSAML 3.x is structured as a Maven multi-module project.
The Message Context has changed to become more modular. MessageHandlers have been added to process the messages using the message context.
The syntax has been changed for some processes: The syntax for using the HTTPRedirectDeflateEncoder has changed to a small degree, mainly due to the new design of the message context.
The syntax for sending SOAP messages has changed substantially.
A lot of package names have changed from version 2 to 3.
Some of the classes have been renamed for example the EntityIdCriteria class used for resolving credentials is renamed to EntityIdCriterion.
The EncryptionParameters class used for specifying encryption options is renamed to DataEncryptionParameters.
Some methods are dropped out or either moved into another class. For example, the Configuration.validateNonSunJAXP method has been removed as it is no longer necessary to validate this, Configuration.validateJCEProviders method has been replaced by the init method of JavaCryptoValidationInitializer.
Changes to Field names: The StatusCode.SUCCESS_URI used in the Artifact Response has been renamed to StatusCode.SUCCESS.

Since there are only a handful of resources which could help you with the migration, the list below would be a savior for you,

Useful Resources

Resources together will make the conversion work

Shibboleth OpenSAML 2- Shibboleth OpenSAML 2 portal will help you look at certain implementation which would not change much when converting to OpenSAML 3.
Shibboleth OpenSAML 3- Shibboleth OpenSAML 3 portal will help you find the packages for the classes from OpenSAML 2, look at the methods available, etc… Especially the API Documentation.
Shibboleth Developers Portal- Shibboleth developers portal is a place where you can ask questions from the community. To ask questions you must subscribe to the mailing list “ dev@shibboleth.net”. More info is available on the top of the developer portal web page.
Stefan Rasmusson’s Book (Guide to OpenSAML V3)- This book provides a guide on the conversion but it is not free. The book was free for a while on the link but was 503 recently so bad luck with that. I’ll most probably continue to blog so that I could at least cover a bit on the book.
Source code access- This webpage will guide you through the process of obtaining the source code straight from the developers by cloning the repository.

Now to the question which you all are wondering of,

Conversion Effort Required

Code wise the conversion won’t be as much as you except. What you will have to do is remove OpenSAML 2 dependencies, add new OpenSAML 3 dependencies, change import statements to the new packages, fix certain methods which have been changed and finally you might have to change some of the available tests if you have any.

The conversion effort is based on the factors below:

Size of the project- If you are just converting a small repository then it would not take more than two to three days to get it working as OpenSAML 2. But it would take time if you have two or more repositories.
Usage of OSGi- This is a little bit tricky because if you are using OSGi things become a lot harder as OpenSAML 3 does not support OSGi. An exact effort mentioning is impossible based on the scenario.

Finally, I would like to sign off while hoping that you’ve absorbed a fair amount of knowledge about the conversion of OpenSAML 2 to OpenSAML 3 and have a good start for the conversion.