Backend Credential Target Endpoint Matching

Overview

The CredentialTargetMatch component provides a strict security function to ensure that credentials stored for a specific backend service are only sent to that service's designated endpoint. When the platform makes an outbound request to a backend, this logic compares the endpoint being dialed against the endpoint configured in the backend's profile.

This mechanism prevents accidental or malicious misdirection of sensitive credentials. It operates by parsing and normalizing two endpoint URL strings—one from the profile and one from the live request—and checking if they resolve to the same network location. The comparison is strict: it requires the scheme, hostname, and port to match exactly after normalization.

This check is a worker-side implementation of the same conceptual validation performed by the Admin API's CredentialTargetGuard.

How it Works

The core logic is encapsulated in the CredentialTargetMatch.sameEndpoint(String profileEndpoint, String dialedEndpoint) method. This method returns true only if both input strings represent the same endpoint target.

The matching process follows these steps:

1. Both the profileEndpoint and dialedEndpoint strings are independently parsed and normalized into a standardized Endpoint representation consisting of a scheme, host, and port.
2. If either string is null, empty, or cannot be parsed into a valid endpoint with a host, the comparison fails, and the method returns false.
3. If both strings are successfully parsed, the two resulting Endpoint objects are compared for equality.
4. A match is found (true) only if the normalized scheme, host, and port are identical for both endpoints.

The diagram below illustrates the flow of an endpoint string through the normalization process.

flowchart TD
    subgraph "Input"
        A[Endpoint String]
    end

    subgraph "Normalization & Parsing"
        B{Is string null or empty?}
        B -- Yes --> C[Result: No Match]
        B -- No --> D[Trim whitespace]
        E{Contains "://"?}
        D --> E
        E -- No --> F[Prepend "https://"]
        E -- Yes --> G[Use as-is]
        F --> H(Parse as URI)
        G --> H

        H -- Fails --> C

        H -- Succeeds --> I{Host present?}
        I -- No --> C
        I -- Yes --> J[Normalize Host: toLowerCase()]

        K{Scheme present?}
        H --> K
        K -- No --> L[Default Scheme: "https"]
        K -- Yes --> M[Normalize Scheme: toLowerCase()]

        N{Port specified?}
        H --> N
        N -- Yes --> O[Use specified port]
        N -- No --> P{Scheme is "http"?}
        P -- Yes --> Q[Default Port: 80]
        P -- No --> R[Default Port: 443]
    end

    subgraph "Normalized Endpoint"
        S([Scheme, Host, Port])
    end

    J --> S
    L --> S
    M --> S
    O --> S
    Q --> S
    R --> S

Endpoint Normalization

Before comparison, each endpoint string undergoes a series of normalization steps:

• Trimming: Leading and trailing whitespace is removed.
• Scheme Defaulting: If the string does not contain a scheme (e.g., example.com), it is prefixed with https://. If a scheme is present, it is converted to lowercase.
• Host Normalization: The host part of the URI is converted to lowercase for case-insensitive comparison. If the URI has no host, parsing fails.
• Port Defaulting: If the port is not explicitly specified in the URI, it is defaulted based on the scheme:
  • http: port 80
  • https: port 443
• Ignored Components: The path, query parameters, and fragment portions of the URI are completely ignored during comparison. For example, https://example.com/api and https://example.com/ are treated as the same endpoint.

API Reference

CredentialTargetMatch.sameEndpoint

Compares two endpoint strings to determine if they refer to the same network destination.

static boolean sameEndpoint(String profileEndpoint, String dialedEndpoint)

Parameters

Returns

Returns true if the normalized scheme, host, and port of both endpoints are identical. Otherwise, returns false.

Examples of Endpoint Matching

The following table shows various input pairs and the resulting boolean match status, illustrating the normalization logic.

Troubleshooting

A comparison will return false under any of the following conditions, indicating that credentials should not be forwarded:

• Scheme, Host, or Port Mismatch: The normalized components are not identical.
• Invalid URI: An input string cannot be parsed as a valid URI, even after prepending a default scheme. This can be caused by illegal characters.
• Missing Host: The parsed URI lacks a host component (e.g., https:///path/only).
• Null or Blank Input: Either profileEndpoint or dialedEndpoint is null, empty, or contains only whitespace.

See Also

• Admin API Credential Target Guard: This worker-side component is a port of similar validation logic found in the Admin API, which governs the initial configuration of backend profiles.

All SOAP-to-REST docs