Java Agents 2024.9

FQDN checks

When FQDN checking is enabled, the agent can redirect requests to different domains, depending on the hostname of the request. Use this feature in environments where the request hostname can be virtual, invalid, or partial.

FQDN checking requires Enable FQDN Checking to be true, Default FQDN to be set to a suitable value, and optionally, FQDN Map to be set to suitable default FQDN.

When FQDN Map is configured, the agent maintains the following maps:

  • Map 1:

    • Key: Incoming hostname without wildcards.

    • Value: Outgoing hostname.

  • Map 2:

    • Key: Incoming hostname with wildcards * and ?.

    • Value: Outgoing hostname.

Map keys are case insensitive. Incoming hostnames are converted to lowercase before the agent maps them, and the agent automatically converts uppercase keys and values to lowercase before mapping.

The agent maps FQDNs as follows:

  1. Searches map 1 for the incoming hostname. If there is a match, the agent redirects the request to the mapped value.

  2. Searches map 2 for a pattern that matches the incoming hostname, iterating through the entries in random order. If there is a match, the agent redirects the request to the mapped value.

  3. Redirects the request to the value in Default FQDN.

Examples

The following example configuration and requests illustrate how the agent checks and remaps FQDNs:

Configuration

  • Enable FQDN Checking: org.forgerock.agents.fqdn.check.enabled=true

  • Default FQDN: org.forgerock.agents.fqdn.default=agent.defaulttest.me

  • FQDN Map:

    • Map 1

      org.forgerock.agents.fqdn.map[agent]=agent.localtest.me org.forgerock.agents.fqdn.map[agent.virtualtest.me]=virtual-host.localtest.me

    • Map 2

      org.forgerock.agents.fqdn.map[agent-*.localtest.me]=agent.localtest.me

Example requests

  • https://agent.localtest.me/app: Does not match any mapping, so the agent redirects it to the default FQDN https://agent.defaulttest.me/app.

  • https://agent/app: The request URL matches the first mapping in map 1, so the agent redirects it to https://agent.localtest.me/app.

  • https://AGENT/app: The request URL matches the first mapping in map 1, because incoming hostnames are converted to lower-case before the agent maps them. The agent redirects the request to https://agent.localtest.me/app.

  • https://agent.virtualtest.me/app: The request URL matches the second mapping in map 1, so the agent redirects it to the virtual host https://virtual-host.localtest.me/app.

  • https://agent-123.localtest.me/app: The request URL matches the mapping in map 2, so the agent redirects it to https://agent.localtest.me/app.