My starter kit lets a tenant create API keys for integrations: send X-API-Key: ak_... instead of a JWT. While adding that, I made a mistake that a security review caught before the release. It's a small, common one, and the fix is one Spring Security class.
The rule: a key can't manage credentials
A key acts as the user who created it, inside the key's tenant. That's convenient, and it means a leaked key is as powerful as its creator. So a key must not be able to touch credentials or accounts. Otherwise a leaked key could mint a new key, or reset a password, and keep access after it's revoked.
The excluded areas are API keys themselves, sign-in and 2FA, the profile, and writes to users and platform administration.
The first version
The first version checked the request path as a string:
String path = request.getRequestURI().substring(request.getContextPath().length());
boolean read = "GET".equalsIgnoreCase(request.getMethod());
return path.startsWith("/api/api-keys")
|| path.startsWith("/api/auth/")
|| path.startsWith("/api/profile")
|| (!read && (path.startsWith("/api/users") || path.startsWith("/api/admin/")));
It looks fine, and the obvious tests passed.
The bypass
getRequestURI() returns the path as sent, still percent-encoded. Spring MVC decodes and normalises the path before it picks a controller. Those two views of the same request can disagree:
GET /api/%61pi-keys
X-API-Key: ak_...
%61 is a. The string check sees /api/%61pi-keys, which doesn't start with /api/api-keys, so the key is accepted. MVC decodes it to /api/api-keys and routes it to the API key controller. A key could list or create keys.
This is the general shape of a whole class of bugs: the security layer and the routing layer parse the same input differently.
The fix: match like MVC matches
Spring Security 7 has PathPatternRequestMatcher, which matches the decoded, normalised path with the same PathPattern syntax MVC uses:
// Matched like Spring MVC matches them (decoded, normalised path), so "/api/%61pi-keys" cannot slip past
private static final PathPatternRequestMatcher.Builder PATHS = PathPatternRequestMatcher.withDefaults();
private static final RequestMatcher CREDENTIAL_MANAGEMENT = new OrRequestMatcher(
PATHS.matcher("/api/api-keys/**"),
PATHS.matcher("/api/auth/**"),
PATHS.matcher("/api/profile/**"),
writes("/api/users/**"),
writes("/api/admin/**"));
private static RequestMatcher writes(String pattern) {
return new OrRequestMatcher(
PATHS.matcher(HttpMethod.POST, pattern),
PATHS.matcher(HttpMethod.PUT, pattern),
PATHS.matcher(HttpMethod.PATCH, pattern),
PATHS.matcher(HttpMethod.DELETE, pattern));
}
A request that matches is simply left unauthenticated, so it's refused like any request without credentials.
And the encoded path is now a test case, next to the plain ones:
mockMvc.perform(get(URI.create("http://localhost/api/%61pi-keys")).header(ApiKeyAuthFilter.HEADER, rawKey))
.andExpect(status().isForbidden());
Two more rules the review added
- The creator must still be allowed in. A key stops working when its creator is disabled or locked, not only when the key is revoked or expires.
- The creator must be older than the key and in the same tenant. Usernames can be reused. If a user is deleted and someone else later registers the same username, the old key must not start acting as the new account.
If you write your own path checks
- Don't make security decisions on
getRequestURI()strings. - Use the same matcher the router uses: in Spring,
PathPatternRequestMatcher. - Put an encoded variant of every protected path in your tests.
Talk to me
This is part of a series about building Arab Enterprise Kit, an Arabic-first, multi-tenant SaaS foundation in Java 25, Spring Boot 4 and Angular 21. There's a free Lite edition on GitHub, and a live demo of the full kit. I build SaaS products and take freelance full-stack and backend projects: mahmoud-farouk-portfolio.vercel.app.
Have you seen a parser mismatch like this in your own security code?
Top comments (0)