Using a Slash Character in Spring URLs

1. Introduction

When we develop web services, we may need to deal with complex or unexpected URL paths that can contain slashes. As a consequence, we may encounter issues with the web servers or frameworks we are using.

Spring specifically can be a bit tricky in this regard due to the default configurations that it provides.

In this tutorial, we’ll show some common solutions and recommendations for handling URLs with slashes in Spring. We’ll also see why we shouldn’t use some common hacks to work around these issues. Keep reading to know more about it!

2. Parse the Request Manually

In our web services, sometimes we need to map all the requests under a certain path to the same endpoint. To make matters worse, we may not know what the rest of the path will look like. We might also need to somehow receive this path as a parameter in order to use it afterward.

Let’s say that we can receive requests with any path under /mypaths:

http://localhost:8080/mypaths/any/custom/path

And suppose we want to store all these different paths in a database to know what requests we’re receiving.

The first solution that will probably come to our minds is to capture the dynamic part of the path into a PathVariable:

@GetMapping("mypaths/{anything}")
public String pathVariable(@PathVariable("anything") String anything) {
    return anything;
}

Unfortunately, we soon find out that this returns a 404 if the PathVariable contains a slash. The slash character is the URI standard path delimiter, and all that goes after it counts as a new level in the path hierarchy. As expected, Spring follows this standard.

We can easily solve this by creating a fallback for all the requests under a certain path by using the ** wildcard:

@GetMapping("all/**")
public String allDirectories(HttpServletRequest request) {
    return request.getRequestURI()
        .split(request.getContextPath() + "/all/")[1];
}

Then we have to parse the URI ourselves in order to get the part of the path we’re interested in.

This solution is very convenient when working with URL-like parameters, but as we’ll see in the next section, it’s not enough for some other cases.

3. Use Query Parameters

In contrast to our previous example, there are other cases where we’re not just mapping different paths but receiving any String as a parameter in the URL.

Let’s imagine that in our previous example, we make a request with a path parameter that contains consecutive slashes:

http://localhost:8080/all/http://myurl.com

At first, we could think that this should work, but we soon realize that our controller returns http:/myurl.com. This happens because Spring Security normalizes the URLs and replaces any double-slash with a single one.

Spring also normalizes other sequences in URLs, such as path traversals. It takes these precautions to prevent malicious URLs from bypassing the defined security constraints, as explained in the official Spring Security documentation.

In these cases, it’s strongly recommended to use query parameters instead:

@GetMapping("all")
public String queryParameter(@RequestParam("param") String param) {
    return param;
}

This way, we can receive any String parameter without these security restrictions, and our web service will be more robust and secure.

4. Avoid Workarounds

The solutions we’ve presented may imply some changes in our mappings design. This could tempt us to use some common workarounds to make our original endpoints work when receiving slashes in the URLs.

The most common workaround is probably to encode the slashes in the path parameters. However, some security vulnerabilities were reported in the past and most web and application servers reacted to it by disallowing the encoded slashes by default. It’s still possible to change this behavior just by changing the corresponding setting, like in Tomcat.

Others like Apache Server went a bit further and introduced an option to allow encoded slashes without decoding them so that they’re not interpreted as path delimiters. In any case, this is not recommended and it can introduce potential security risks.

On the other hand, web frameworks also take some precautions. As we’ve seen before, Spring adds some mechanisms as protection against less strict servlet containers. So, in case we allow encoded slashes in our server, we still have to allow them in Spring.

Finally, there are other kinds of workarounds like changing the URI normalization that Spring provides by default. As before, we should be very cautious if we change these defaults.

5. Conclusion

In this short article, we’ve shown some solutions for dealing with slashes in URLs in Spring. We’ve also introduced some security problems that can arise if we change the default configurations of servers or frameworks like Spring.

As a rule of thumb, query parameters are usually the best solution to deal with slashes in URLs.