Credential Target Guard

Overview

The Credential Target Guard is a security component that prevents stored secrets, such as connector passwords, from being redirected to an arbitrary destination. It enforces a strict security principle: a stored secret can only be sent to the endpoint and for the user that it was originally saved for.

This component solves a specific security problem: an administrative user who is permitted to manage system configurations but not to view stored secrets must not be able to exfiltrate those secrets by modifying a configuration to point to a different host. The guard acts as a check before any operation that combines a stored secret with a caller-supplied target (e.g., a hostname or username). If the target differs from the one associated with the stored secret, the guard requires the API consumer to supply the secret again in the current request.

This check is invoked by internal services, such as the Admin API, whenever a request might use a stored secret. It is not a standalone service that API consumers call directly.

How it Works

The core enforcement mechanism is the requireSecretForNewTarget method. When an API request attempts to use a stored secret, this guard's logic is triggered to validate the request.

The validation follows these steps:

1. It checks if a secret is stored for the given configuration. If no secret is stored, the guard takes no action.
2. If a secret is stored, it checks if the request attempts to change the target destination. A "target change" can be a modification of the endpoint URL, the username, or other security-sensitive settings like TLS verification.
3. It checks if the API consumer has re-supplied the secret in the current request.
4. The request is allowed to proceed only if:
   • No secret was stored in the first place.
   • The target destination has not changed.
   • The target destination has changed, but the secret was also re-supplied in the request.

If a stored secret exists, the target has changed, and the secret was not re-supplied, the guard rejects the operation by throwing an IllegalArgumentException, which results in an HTTP 400 Bad Request response to the API consumer.

flowchart TD
    A[Start: Request to use a stored secret] --> B{Is a secret stored?};
    B -- No --> G[Allow Request];
    B -- Yes --> C{Has the target destination changed?};
    C -- No --> G[Allow Request];
    C -- Yes --> D{Was the secret re-supplied in the request?};
    D -- No --> E[Reject Request with HTTP 400];
    D -- Yes --> G[Allow Request];

Target Comparison Logic

The guard uses specific comparison logic to determine if a target has changed.

Endpoint (sameEndpoint)

Two endpoints are considered the same if they have an identical scheme, host, effective port, and path.

• Scheme: Compared case-insensitively (e.g., https is the same as HTTPS). If no scheme is provided, https:// is assumed.
• Host: Compared case-insensitively (e.g., api.example.com is the same as API.EXAMPLE.COM).
• Port: The effective port is used. If a port is not specified, it defaults to 80 for http and 443 for https.
• Path: Compared case-sensitively after normalization. An empty path is treated as /, and a single trailing slash is ignored (e.g., /v1/ becomes /v1).
• Query and Fragment: The query string and fragment parts of the URL (e.g., ?foo=bar and #section) are ignored during comparison.

Username (sameUsername)

Usernames are compared case-sensitively after trimming leading and trailing whitespace. A blank or empty candidate username is interpreted as "use the saved value" and passes the check.

Host Header (sameHostHeader)

Comparison of the Host header is distinct from endpoint host comparison.

• A blank resolved Host header value is treated as a change if a value was previously set. This is because clearing the header causes the request to fall back to the endpoint's host, potentially targeting a different virtual host.
• Comparison is case-insensitive for ASCII-only hostnames. Unicode lookalikes are not folded, so non-ASCII hostnames are compared case-sensitively.

API Reference

The CredentialTargetGuard provides several static methods used internally to perform its checks.

requireSecretForNewTarget

This method is the primary enforcement point. It throws an IllegalArgumentException if a stored secret would be sent to a new target without being re-supplied.

There are two overloads for this method.

Parameters for simple secrets:

Parameters for structured secrets:

This overload is for integrations where the secret is part of a larger structured object, and it allows for a custom error message.

Boolean Helper Methods

These methods are used to determine if a target has changed.

Troubleshooting

When the Credential Target Guard rejects a request, the API responds with an HTTP 400 Bad Request status code. The response body contains a message explaining why the request was denied.

• | The <system> TLS-insecure setting differs from the saved one. Re-enter the <system> password to test with a different TLS setting, for example {"tlsInsecure": false, "password": "..."}; the saved password is only ever sent with the saved TLS setting. | The API consumer attempted to use a stored secret while changing the TLS verification setting (e.g., tlsInsecure). - |

Example: Correcting a Rejected Request

An API consumer attempts to change the TLS setting for a connector without re-entering the password.

Rejected Request Body:

{
  "tlsInsecure": false
}

This request would be rejected with an HTTP 400 error and a message similar to the one for TLS setting changes.

Corrected Request Body:

To fix this, the consumer must re-supply the password along with the changed setting.

{
  "tlsInsecure": false,
  "password": "<SECRET_PASSWORD>"
}

This request will pass the guard's check because the password was supplied again.

See Also

• Documentation on configuring system connectors.
• Guides for managing backend service profiles.

All SOAP-to-REST docs