OpenAPI Validation Proposal and Design

Objective

In zonal architectures a valuable security mechanism is the ability to terminate messages that do not match an expected request in the zone nearest to the outside world - usually termed the demilitarized zone DMZ. In discussions with other gateway providers, this is becoming a more frequent ask amongst users of API Gateways.

The aim of this proposal is to provide a filter for the Spring Cloud Gateway that uses the Atlassian Swagger Request Validator to inspect the body of application/json requests and terminate with a 4xx error if the request if it does not match the target services OpenAPI specification.

Design Considerations

Reading the Body

The pre-requisite of this working is that the body of the request must be read. No modification of the body is required, however it does need to be converted into the SimpleRequest type recognised by the validator library. There are several ways that the body can be read - using custom code to cache the body or integrating with some of the code from Spring Cloud Gateway that provides a similar service for Retry Logic (e.g. emitting a EnableBodyCachingEvent). Would this be the intended usage of the event? Is there a better way to implement this?

Locating the Specification

The location of the OpenAPI specification to validate against is the next problem to solve. In the prototype I have we use a pre-flight strategy (similar to CORS) that makes the request to the target service and requests the OpenAPI specification from a well known path, it then goes on to cache the specification. If a redeployment happens this can then cause issues, unless a concept of versioning is built into the gateway - which is likely too much for a general solution.

For this reason it would be necessary to provide multiple options and functionality around the validation logic. For example on a failure re-acquire the OpenAPI specification. Alternatively, as is true with many reverse proxying/API Management tools sourcing the specification from a fixed location might be necessary. Or provide a custom override that is specific to the end users specification sourcing strategy. The design should implement the first two and leave an open configuration point for the developer to use a custom bean.

Support Alternate Validators

The final point is whether this whole solution should provide the ability to plug in different types of validators for different content types. E.g. if I want to use the OpenAPI validator to inspect JSON and an XSD to inspect XML? This would need to be factored into the design, and would likely make the location strategy relevant to all types of validators.

Project Location Considerations

Given the trade offs between performance and caching of the request body the question arises as to whether this should be an external project or added as functionality into the Spring Cloud Gateway core?

Open Questions

• What is the best way to read the body for a library providing validation?
• Where is the best location for the project to reside?

I would be interested in feedback on this or thumbs up if others are also looking for this pattern. I have a working prototype that I'd now like to write as a full solution.

No source files or tests are named. Start by reviewing the working prototype mentioned in the issue and the Spring Cloud Gateway body-caching and specification-location questions; the design is only complete once the project location, request-body handling, specification sourcing, and validator extension points are decided.