PingGateway 2024.9

UriPathRewriteFilter

Rewrite a URL path, using a bidirectional mapping:

  • In the request flow, fromPath is mapped to toPath.

  • In the response flow, toPath is mapped to fromPath.

PingGateway overwrites a response header only when all of the following conditions are true:

  • The response includes a header such as Location or Content-Location

  • The URI of the response header matches the mapping

  • The value of response header is a relative path or its scheme://host:port value matches the base URI.

Usage

{
  "name": string,
  "type": "UriPathRewriteFilter",
  "config": {
    "mappings": object,
    "failureHandler": Handler reference
  }
}

Properties

"mappings": object, required

One or more bidirectional mappings between URL paths. For example mappings, request scenarios, and an example route, refer to Examples.

{
  "mappings": {
    "/fromPath1": "/toPath1",
    "/fromPath2": "/toPath2",
    ...
  }
}

Paths are given by a configuration expression<string>. Consider the following points when you define paths:

  • The incoming URL must start with the mapping path.

  • When more than one mapping applies to a URL, the most specific mapping is used.

  • Duplicate fromPath values are removed without warning.

  • Trailing slashes / are removed from path values.

  • If the response includes a Location or Content-Location header with a toPath in its URL, the response is rewritten with fromPath.

"failureHandler": handler reference, optional

Failure handler to be invoked if an invalid URL is produced when the request path is mapped, or when the response Location or Content-Location header URI path is reverse-mapped.

Provide an inline handler declaration, or the name of a handler object defined in the heap. See also Handlers.

Default: HTTP 500

Examples

Valid and invalid mapping examples

The following mapping examples are valid:

  • Single fromPath and toPath

    "mappings": {
  "/fromPath1": "/toPath1",
  "/fromPath2": "/toPath2"
}

  • Expressions in the fromPath and toPath

    "mappings": {
  "/${join(array(`fromPath`, 'path1'), `/`)}": "/${join(array(`toPath`, 'path2'), `/`)}"
}

  • Expressions in the fromPath and toPath that use predefined heap properties

    "mappings": {
  "${fromPath}": "${toPath}"
}

  • No mappings—the configuration is valid, but has no effect

    "mappings": { }

  • Duplicate toPath

    "mappings": {
  "/fromPath1": "/toPath",
  "/fromPath2": "/toPath"
}

  • Duplicate fromPath—the configuration is overwritten without warning

    "mappings": {
  "/fromPath": "/toPath1",
  "/fromPath": "/toPath2"
}

The following mapping examples are not valid

  • No toPath

    "mappings": {
  "/fromPath": ""
}
    "mappings": {
  "/fromPath": "${unknown}"
}

  • Invalid toPath

    "mappings": {
  "/fromPath": "${invalidExpression}"
}

  • No fromPath

    "mappings": {
  "": "/toPath"
}
    "mappings": {
    "${unknown}": "/toPath"
}

  • Invalid fromPath

    "mappings": {
    "${invalidExpression}": "/toPath"
}

Example request scenarios

Description Mapping Inbound URI Rewritten URI

Basic path

 
"mappings": {
  "/fromPath": "/toPath"
}

http://example.com/fromPath/remainder

http://example.com/toPath/remainder

Root context, where the inbound request URI has a / path segment

 
"mappings": {
  "/": "/rootcontext"
}

http://example.com/

http://example.com/rootcontext/

Root context, where the inbound URI has a / path segment

 
"mappings": {
  "/rootcontext": "/"
}

http://example.com/rootcontext/

http://example.com/

Root context, where the inbound request URI has an empty path

 
"mappings": {
  "/": "/rootcontext"
}

http://example.com

http://example.com/rootcontext

Root context, where the rewritten URI has an empty path

 
"mappings": {
  "/rootcontext": "/"
}

http://example.com/rootcontext

http://example.com

Root context, with path remainder

 
"mappings": {
  "/": "/rootcontext"
}

http://example.com/remainder

http://example.com/rootcontext/remainder

Root context, with path remainder

 
"mappings": {
  "/rootcontext": "/"
}

http://example.com/rootcontext/remainder

http://example.com/remainder

Root context, where the trailing / on toPath is ignored

 
"mappings": {
  "/": "/rootcontext/"
}

http://example.com/remainder

http://example.com/rootcontext/remainder

Path with dot-segments:

 
"mappings": {
  "/fromPath": "/toPath1/../toPath2"
}

http://example.com/fromPath

http://example.com/toPath1/../toPath2

Path with syntax:

 
"mappings": {
  "/fromPath;v=1.1": "/toPath,1.1"
}

http://example.com/fromPath;v=1.1

http://example.com/toPath,1.1

Path with syntax:

 
"mappings": {
  "/$fromPath": "/$toPath"
}

http://example.com/$fromPath

http://example.com/$toPath

Path with query parameters

 
"mappings": {
  "/fromPath": "/toPath"
}

http://example.com/fromPath?param1&param2=2

http://example.com/toPath?param1&param2=2

Path with fragment

 
"mappings": {
  "/fromPath": "/toPath"
}

http://example.com/fromPath#fragment

http://example.com/toPath#fragment

Example route

The example route changes a request URL as follows:

  • The baseURI overrides the scheme, host, and port of a request URL.

  • The UriPathRewriteFilter remaps the path of a request URL.

    Requests to http://ig.example.com:8080/mylogin are mapped to http://app.example.com:8081/login.

    Requests to http://ig.example.com:8080/welcome are mapped to http://app.example.com:8081/home.

    Requests to http://ig.example.com:8080/other are mapped to http://app.example.com:8081/not-found, and result in an HTTP 404.

    Requests to http://ig.example.com:8080/badurl are mapped to the invalid URL http://app.example.com:8081[, and invoke the failure handler.

{
  "name": "UriPathRewriteFilter",
  "baseURI": "http://app.example.com:8081",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "UriPathRewriteFilter",
          "config": {
            "mappings": {
              "/mylogin": "/login",
              "/welcome": "/home",
              "/other": "/not-found",
              "/badurl": "["
            },
            "failureHandler": {
              "type": "StaticResponseHandler",
              "config": {
                "status": 500,
                "headers": {
                  "Content-Type": [
                    "text/plain"
                  ]
                },
                "entity": "Invalid URL produced"
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  }
}

More information

org.forgerock.openig.filter.UriPathRewriteFilter

RFC 3986: Path