POST data preservation

When POST data preservation is enabled and an unauthenticated client POSTs data to a protected resource, the agent stores the data in the POST data preservation cache and redirects the client for login. After successful authentication, the agent recovers the cached data and automatically submits it to the protected resource.

The POST data can be any POST content, such as a single-part HTML form or a file upload.

Use POST data preservation in environments where clients submit form data and have short-lived sessions.

The following image shows a simplified data flow, where an unauthenticated client POSTs data to a protected web application:

Java Agent guarantees the integrity of the data, and the authenticity of the client as follows:

An unauthenticated client requests a POST to a protected resource.
The agent stores the POST data temporarily, and then generates the following unique identifiers:
- An identifier in the goto URL for the authentication response
- An identifier in a cookie
The use of two unique identifiers provides robust security, because a hacker must steal the goto URL and the cookie.
The agent redirects the client to AM for authentication, and includes the cookie in the redirect.
The client authenticates with AM.
AM provides an authentication response to the goto URL with the unique identifier, and includes the cookie.
The agent validates both identifiers, and recovers the POST data from the dummy internal endpoint given in the goto URL.

If the goto URL contains the incorrect identifier, or cannot provide a cookie containing the correct second identifier (for example, because it has expired), the agent denies the request.

The presence of the unique identifier in the goto URL ensures that requests at the URL can be individually identified. Additionally, the code makes it more difficult to hijack user data, because there is little chance of guessing the code within the login window.
The agent sends a self-submitting form to the client browser, that includes the form data the user attempted to post in step 1. The self-submitting form POSTs to the protected resource.

Configure POST data preservation

Configure POST data preservation by using the agent properties listed in POST Data Preservation in the Properties reference, or on the Advanced tab of the AM admin UI.

Security considerations for storing POST data in files

By default, POST data is stored in the in-memory cache. Consider the following points if you configure POST Data Preservation in Files or Cache to store POST data in the file system:

Payloads from unauthenticated users are stored in the agent file system. If your threat evaluation does not accept this risk, store the data in the cache, or set POST Data Preservation in Files or Cache to false.
Restrict access to the POST Data Preservation File Directory, to mitigate the risk of permissive access or leakage of personally identifiable information (PII).
Limit the amount of stored POST data to mitigate the risk of DoS attacks, by configuring POST Data Preservation Storage Size or Max Entries in POST Data Preservation Storage.
Remove expired POST data as soon as possible by configuring the POST Data Preservation Directory Sweep Interval.
Identify threats in POST data before it is deleted, by making sure that Intrusion Detection Systems inspect the data within the time specified by POST Data Preservation Directory Sweep Interval.

Defend against CSRF attacks when using POST data preservation

Cross-site request forgery attacks (CSRF or XSRF) can be a cause of serious vulnerabilities in web applications. It is the responsibility of the protected application to implement countermeasures against such attacks, because Java Agent cannot provide generic protection against CSRF. ForgeRock recommends following the latest guidance from the OWASP CSRF Prevention Cheat Sheet.

When POST data preservation is enabled, captured POST data that is replayed appears to come from the same origin as the protected application, not from the site that originated the request. Therefore, CSRF defenses that rely solely on checking the origin of requests, such as SameSite cookies or Origin headers, are not reliable. ForgeRock strongly recommends using token-based mitigations against CSRF, and relying on other measures only as a defense in depth, in accordance with OWASP guidance.

CSRF attack when POST data preservation is disabled

The following image shows a simplified data flow during a CSRF attack on an authenticated client when POST data preservation is disabled. In this limited scenario, the agent SameSite setting is enough to defend the web application:

CSRF attack when POST data preservation is enabled

The following image shows a simplified data flow during a CSRF attack on an authenticated client when POST data preservation is enabled. In this scenario, the SameSite setting is not enough to defend the web application:

Java Agents 2024.3