Routed Request Path for Authorization

Overview

The RoutedRequestPath component is a security utility that produces a canonical, normalized string representation of an HTTP request's path. Its primary purpose is to resolve a class of security vulnerabilities where the path used for authorization checks differs from the path the underlying web framework uses for routing.

This component solves the problem of "allow-list bypass" attacks. Such attacks exploit variations in a request URI—such as percent-encoding (%70 instead of p) or matrix parameters (/path;param=val/resource)—to circumvent security policies that match on simple string representations of the path.

RoutedRequestPath is designed to be used by security filters that execute before the main request dispatcher. It takes an HttpServletRequest as input and produces a normalized path string. Authorization logic must use this string to ensure that security decisions are based on the exact same path interpretation that the routing engine will use. If a path cannot be unambiguously resolved, the component signals this, allowing the caller to fail-closed and deny the request.

How it Works

The RoutedRequestPath component derives the canonical path by replicating the normalization and parsing logic of the platform's Spring-based routing framework. This ensures that the path used for authorization is identical to the path used for dispatching the request to a handler.

The process follows these steps:

1. Parse Request: The process begins when the static method RoutedRequestPath.of() is called with an HttpServletRequest.
2. Invoke Spring Parser: It uses Spring's ServletRequestPathUtils.parse() utility to parse the raw request URI into a RequestPath object. This step does not use a cache, ensuring it does not interfere with later processing by the DispatcherServlet.
3. Isolate Application Path: It extracts the pathWithinApplication(), which is a PathContainer representation of the path. This removes any server context path or servlet prefix, focusing only on the part of the path relevant to application routing.
4. Render Canonical String: The PathContainer is then rendered into a final string according to a strict set of rules. This rendering logic is the core of the component's security function.

The rendering logic performs the following transformations:

• Decodes Segments: Each path segment is taken from its valueToMatch() representation. This value is percent-decoded, and any matrix parameters (e.g., ;key=value) are stripped.
• Validates Segments: It explicitly rejects paths containing segments that are decoded to . or .. or that contain an encoded path separator (/). These are characteristics of path traversal or path confusion attacks.
• Collapses Separators: Runs of multiple forward slashes (//) are collapsed into a single /.
• Preserves Trailing Slash: A trailing / on the original path is kept in the output, as the routing engine treats paths with and without a trailing slash differently.

If at any point parsing fails or a validation rule is violated, the component returns null, signaling to the caller that the path is malformed or ambiguous and the request should be rejected.

flowchart TD
    subgraph RoutedRequestPath.of()
        A[HttpServletRequest] --> B{ServletRequestPathUtils.parse(request)};
        B --> C[RequestPath];
        C --> D{pathWithinApplication()};
        D --> E[PathContainer];
        E --> F{Render & Validate};
    end

    subgraph "Fail-Closed Conditions"
        style "Fail-Closed Conditions" fill:#fdd,stroke:#f00,stroke-width:2px
        B -- on any RuntimeException --> G[return null];
        F -- on validation failure --> G[return null];
    end

    F -- on success --> H[Canonical Path String];

    A -.-> G;

    subgraph Caller
        H --> I{Authorization Logic};
        G --> I;
        I --> J{Decision: Allow / Deny};
    end

API Reference

RoutedRequestPath is a final utility class with a single static method and cannot be instantiated.

public static String of(HttpServletRequest request)

Returns the canonical, routed path for a given request, or null if the path cannot be resolved unambiguously.

• Parameters:
  • request (HttpServletRequest): The incoming HTTP servlet request to analyze.
• Returns:
  • A String containing the normalized path for authorization checks.
  • null if the path is ambiguous, malformed, or invalid. Callers must treat a null return value as a fail-closed condition, typically by denying the request or applying the most restrictive security policy.

Example Normalizations

The following table illustrates how RoutedRequestPath normalizes various input URIs.

Fail-Closed Conditions

The RoutedRequestPath.of() method is designed to be fail-closed, returning null whenever a path cannot be safely and unambiguously determined. Callers must interpret a null result as a signal to reject the request.

A null value is returned under the following circumstances:

• Null Input: The HttpServletRequest object or its URI is null.
• Parsing Exceptions: Any RuntimeException is thrown during path parsing. This includes, but is not limited to:
  • IllegalArgumentException from a malformed percent-encoding sequence (e.g., /path/%GZ).
  • Exceptions thrown during context-path resolution.
  • NullPointerException if the servlet container provides an invalid HttpServletMapping.
• Invalid Segment Content: After decoding, a path segment is found to contain invalid characters or sequences. This is a security check to prevent path traversal and path confusion. The specific violations are:
  • A segment contains a forward slash (/). Example: res%2Fource.
  • A segment is exactly . (a single dot).
  • A segment is exactly .. (a double dot).

See Also

• Admin Authorization Filter: This component is a primary consumer of RoutedRequestPath. The filter uses the normalized path to make consistent and secure authorization decisions for administrative endpoints.

All SOAP-to-REST docs