Admin API License Watermarking

Overview

The LicenseWatermarkFilter is a servlet filter that intercepts every incoming request to the Admin API. Its primary function is to apply a "watermark" that identifies the active license associated with the request. This watermarking serves two purposes:

1. Diagnostic Logging: It injects the customer_id into the Mapped Diagnostic Context (MDC) for logging. This allows all log entries generated during the processing of a request to be tagged with the customer identifier from the active license, simplifying log analysis and troubleshooting.
2. Response Identification: It adds a unique X-S2R-License HTTP header to the response. This header provides a quick, non-secret way to identify the license state of the instance that handled the request.

The filter runs after authentication and authorization have been completed but before the core business logic of the API endpoint is executed. This ensures that the watermarking information is available to all subsequent processing steps and is included in the final response.

How it works

The LicenseWatermarkFilter processes requests in a sequence of steps designed to be both efficient and safe for the application's stability.

sequenceDiagram
    participant C as API Consumer
    participant A as Admin API
    participant F as LicenseWatermarkFilter
    participant V as License Validator
    participant L as Logging Context (MDC)

    C->>A: Sends API Request
    A->>F: Invokes filter
    alt Request path starts with /actuator/
        F-->>A: Skips filtering
    else Request path is processed
        F->>V: currentState()
        V-->>F: Returns LicenseState
        F->>F: Resolves customer_id from state
        F->>L: MDC.put("customer_id", ...)
        F->>F: Resolves header value from state
        F->>A: setHeader("X-S2R-License", ...)
        F->>A: Passes request to next filter
        A-->>C: Returns Response (with header)
        Note right of F: In 'finally' block
        F->>L: MDC.remove("customer_id")
    end

For every request that does not target an /actuator/ endpoint, the filter performs the following actions:

1. Fetch License State: It calls the LicenseValidator to retrieve the current LicenseState. This operation is wrapped in an exception handler; if it fails, the state is considered null, and the filter proceeds gracefully.
2. Set Logging Context: It determines the appropriate customer_id based on the license state and adds it to the MDC using the key customer_id. This value will be automatically included in relevant log messages.
3. Set Response Header: It calculates a license watermark and sets it as the value for the X-S2R-License response header. The header is omitted if a license state cannot be determined.
4. Chain to Next Filter: It passes the request and response objects to the next filter in the chain for further processing by the application.
5. Clean Up Logging Context: In a finally block, it removes the customer_id from the MDC. This is a critical step to prevent the customer ID from "leaking" and being associated with logs from a different request, which might be processed by the same thread.

Filter Execution Order

The LicenseWatermarkFilter is configured to run at a specific point in the request processing chain:

• After authentication and authorization filters (IdpAuthFilter, AdminAuthorizationFilter). This ensures that its logic only executes for authenticated requests and that the logging context it sets is available to authorized controllers.
• Before the primary business logic of the API. This guarantees that the X-S2R-License header is added to the response before it is committed and sent back to the API consumer.

Actuator Path Exclusion

Watermark Components

The filter generates two distinct pieces of information based on the current license state.

X-S2R-License Response Header

This HTTP header is added to all successful Admin API responses (except for /actuator/ endpoints).

customer_id Logging Context (MDC)

This key is added to the logging context for the duration of a single request.

Example: Full License Watermark Calculation

For a full, active license, the X-S2R-License header value is derived from the license's installation ID.

1. Start with the License Installation ID (UUID): Assume the licenseId is 123e4567-e89b-12d3-a456-426614174000.

2. Convert to String and Hash: The filter converts the UUID to its string representation and computes its SHA-256 digest.

3. Truncate the Hash: The filter takes the first 8 bytes of the resulting digest, which corresponds to the first 16 characters of the hexadecimal representation.

   • Full SHA-256 Hash: f33a8b2a8d7373336295b9588969352e435914620f3cce9868755f7324c7e2a1
   • Truncated Value: f33a8b2a8d737333

4. Set the HTTP Header: The resulting response will include the following header:

   X-S2R-License: f33a8b2a8d737333
   

Troubleshooting

License State Unavailable

If the LicenseValidator fails to retrieve the current license state (e.g., due to a database connection issue), the LicenseWatermarkFilter handles this gracefully:

• A debug message is logged containing the exception details (e.g., S2R-LICENSE watermark — license state unavailable: ...).
• The customer_id in the MDC is set to unlicensed.
• The X-S2R-License header is omitted from the response.

The request will proceed, but it will be watermarked as unlicensed.

See Also

• Identity Provider Authentication: The filter that runs before this one to establish the user's identity.
• Admin Authorization: The filter that runs after authentication but before watermarking to confirm the user has the necessary permissions.

All SOAP-to-REST docs