WSO2 APIM: Schema Validation After Mediation Policy?

Hey guys! Today, we're diving deep into a tricky issue in WSO2 API Manager (APIM) version 4.6.0 related to schema validation. It seems there's a discrepancy between the expected behavior, as per the documentation, and what's actually happening in the system. Let's break it down and see what's going on.

The Problem: Schema Validation After Mediation

In the latest version of WSO2 APIM, a peculiar behavior has been observed. When schema validation is enabled for a REST API in the Publisher Portal, it doesn't kick in when you'd expect it to. Instead, it waits until after all the operation mediations have been executed. This is because the schema validator is added as a handler after the APIManagerExtensionHandler. This placement is the root cause of the problem, preventing schema validation from occurring before the mediation policy execution.

To illustrate, let's look at the handler configuration in velocity_template.xml:

<handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.SchemaValidator"/>

According to the APIM documentation, which you can find here, all handlers are supposed to engage before any mediation policies are applied. This ensures that requests are validated early in the process, preventing potentially harmful or invalid requests from reaching the backend.

This order of execution is crucial for maintaining the integrity and security of your APIs. By validating the schema upfront, you can catch errors and malicious payloads before they have a chance to impact your system. This not only improves performance but also enhances the overall security posture of your API infrastructure. The current implementation, however, deviates from this principle, leading to potential vulnerabilities and unexpected behavior.

Why is this happening?

The logic responsible for this behavior resides within the velocity_template.xml file. Specifically, the way handlers are added and the conditional check for enabling schema validation dictate the order of execution. Here’s a snippet from the file:

## print the handlers
#if( $handlers.size() > 0 )
<handlers xmlns="http://ws.apache.org/ns/synapse">
#foreach( $handler in $handlers )
<handler xmlns="http://ws.apache.org/ns/synapse" class="$handler.className">
#if($handler.hasProperties())
#set ($map = $handler.getProperties() )
#foreach($property in $map.entrySet())
<property name="$!property.key" value="$!property.value"/>
#end
#end
</handler>
#end
## check and set enable schema validation
#if($enableSchemaValidation)
<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.SchemaValidator"/>
#end
</handlers>
#end
#end

Ideally, the org.wso2.carbon.apimgt.gateway.handlers.security.SchemaValidator should be included in the handlers array, which is passed from a specific part of the codebase. This array is crucial because it dictates the order in which handlers are invoked. To fix the issue, the schema validator needs to be added to this array before the APIManagerExtensionHandler. This would ensure that schema validation is performed early in the request processing pipeline, aligning with the intended behavior and the documentation.

The relevant code snippet where the handlers array is managed can be found in the TemplateBuilderUtil.java file within the WSO2 APIM codebase. Specifically, lines 353-361 in the linked GitHub repository show how the handlers are being managed. Ensuring the schema validator is added to this array in the correct order is essential for resolving the issue.

The Documentation's View

The APIM documentation clearly states that all handlers should engage before mediation policies. This is a fundamental aspect of the API management framework, designed to ensure that requests are validated and processed correctly before any custom logic is applied. The current behavior, where schema validation occurs after mediation, contradicts this principle and can lead to unexpected consequences.

Reproducing the Issue: A Step-by-Step Guide

To really understand the issue, let's walk through the steps to reproduce it. This will give you a hands-on understanding of what's going on and why it's important.

1. Create the PizzaShackAPI: First, you'll need a sample API to work with. The PizzaShackAPI is a common example used in WSO2 APIM, so let's use that. If you don't have it already, create it in your APIM environment.
2. Enable Schema Validation: Now, this is where the magic happens. In the Publisher Portal, enable schema validation for your API. This setting tells APIM to validate incoming requests against a predefined schema.
3. Add a Log Policy to the request flow: Next, we'll add a Log Policy to the request flow. This policy will simply log some information about the request, and it will help us track when it's being executed in relation to the schema validation.
4. Invoke the API with an invalid request payload: Now, let's send a request to the API that violates the schema. This could be missing required fields, incorrect data types, or any other schema violation. The goal here is to trigger the schema validation.
5. Notice that the Log Mediation Policy is executed before Schema Validation: This is the key observation. You'll see in the logs that the Log Mediation Policy is executed before the schema validation kicks in. This confirms that the schema validation is happening later in the process than it should.

By following these steps, you can clearly see the issue in action. The Log Policy, which represents a mediation policy, is executed before the schema validation, contrary to the documented behavior.

Impact and Implications

The implications of this issue are significant. If schema validation occurs after mediation, it means that invalid requests might be processed further than they should. This can lead to:

• Security vulnerabilities: Malicious payloads might bypass schema validation and reach the backend, potentially causing harm.
• Performance issues: Invalid requests might consume resources before being rejected, impacting overall API performance.
• Unexpected behavior: The API might behave unpredictably if it receives invalid data.

Therefore, it's crucial to address this issue to ensure the integrity and reliability of your APIs.

The Fix: Reordering the Handlers

The solution to this problem lies in reordering the handlers. As mentioned earlier, the org.wso2.carbon.apimgt.gateway.handlers.security.SchemaValidator needs to be included in the handlers array before the APIManagerExtensionHandler. This will ensure that schema validation is performed early in the request processing pipeline.

This fix involves modifying the TemplateBuilderUtil.java file and ensuring that the schema validator is added to the handlers array in the correct order. Once this change is made, the schema validation will occur before any mediation policies are executed, aligning with the documentation and the intended behavior of the API Manager.

Version Affected

This issue has been identified in version 4.6.0 of WSO2 APIM. If you're using this version, it's important to be aware of this behavior and consider implementing the fix.

Environment Details

This issue is observed across different environments running WSO2 APIM 4.6.0. It's not specific to a particular operating system or configuration. However, always make sure to test any changes in a non-production environment before deploying them to production.

Conclusion

So, there you have it! Schema validation happening after mediation in WSO2 APIM 4.6.0 is a real issue that can have significant implications. By understanding the problem, reproducing it, and knowing the fix, you can ensure that your APIs are secure and reliable. Remember, validating your schemas early is crucial for maintaining the integrity of your API ecosystem.

For further reading on API Security, you might find valuable insights on the OWASP website (https://owasp.org/). They offer a wealth of information on web application security, including API security best practices.