The SAML module in Mendix enables Single Sign-On (SSO) by integrating your application with external identity providers like Azure Active Directory (Azure AD). It facilitates encrypted communication, streamlines user access management, and strengthens application security.

Regularly upgrading your Mendix app and the SAML module is essential to ensure optimal security, performance, and compatibility. This guide walks you through the secure upgrade process and outlines common issues and their solutions.

What is SAML?

SAML (Security Assertion Markup Language) is an open standard that enables secure authentication and authorization between identity providers and service providers. It is commonly used for SSO to offer users seamless access across systems without needing to log in repeatedly.

Steps to Upgrade

1. Upgrade the Mendix Project

• For Mendix 7: Update your app to version 7.23.23.
• For Mendix 8: Update your app to version 8.18.9.

Ensure that any deprecated features are addressed and check the Mendix release notes for any breaking changes.

2. Update the SAML Module

• Mendix 7: Use SAML module version 1.15.4 or later.
• Mendix 8: Use SAML module version 2.1.4 or later.

These versions include critical fixes for Azure AD integration.

3. Ensure Compatibility

• Run your project locally to verify successful Java compilation.
• Watch for JAR file conflicts during testing, which are common when upgrading modules

4. Commit Changes

Once the application runs error-free:

• Commit all changes to your version control system.

5. Deploy to QA

• Deploy the updated application to your QA environment.
• Perform end-to-end testing to validate stability.

6. Test SSO Functionality

• Confirm SSO works as expected across all user roles.
• Test all user authentication workflows involving the SAML module.

Troubleshooting Common Issues

Issue 1: SAML v2.15.3 Error

Error Message:

org.opensaml.xml.signature.impl.CryptoBinaryBuilder cannot be cast to org.opensaml.core.xml.XMLObjectBuilder

Cause: Conflicting version of opensaml JAR in the userlib.

Fix:

Delete org.apache.servicemix.bundles.opensaml-2.6.0_3 from the userlib folder.

Clean the deployment directory.

Rebuild and retest the application.

Solution:

1. Remove the JAR file org.apache.servicemix.bundles.opensaml-2.6.0_3 from the userlib folder.
2. Clean the deployment directory.
3. Retest the application.

Issue 2: Java Code Compilation Errors

Problem:
Compilation errors, like “cannot find symbol”, may appear when running the project locally. These errors are typically caused by conflicting JAR files in the userlib folder.

Solution:

1. Open your project in Eclipse.
2. Identify the Java file causing the error (it will display an error message in Eclipse).
3. Use CTRL + SHIFT + T in Eclipse to search for the conflicting class.
4. Look for duplicate libraries in the userlib folder.
5. Delete the older versions of the conflicting libraries.
6. Clean the deployment directory in Mendix Studio Pro.
7. Retest the project locally.

Issue 3: APPLICATION_SOAP_XML Compilation Error

Error Message:

cannot find symbol: variable APPLICATION_SOAP_XML

Cause: Missing or incompatible libraries.

Fix:

1. Remove the following JARs from the userlib folder:
   • httpcore-4.4.11
   • org.apache.servicemix.bundles.opensaml-2.6.0_3
2. Clean the deployment directory.
3. Rebuild the project.

Example:

error: cannot find symbol

httpPost.setEntity(new ByteArrayEntity(authnState.getModifiedSOAPRequest().getBytes(), ContentType.APPLICATION_SOAP_XML));

Resolution:

• Remove conflicting JARs.
• Clean and rebuild the project.

Upgrading your Mendix app and the SAML module ensures security, reliability, and compatibility with modern identity systems like Azure AD. By following the steps in this guide, you can:

• Minimize downtime
• Prevent authentication errors
• Keep your application secure and compliant

Note: Schedule regular reviews of your app dependencies to avoid unexpected issues in production