Java Agents 2023.11

Authentication Fail Reason Parameter Value Map

After an authentication failure, malicious users can use the information you expose to gain access to the system. Map the reason for authentication failure to something generic, or something that is meaningful inside your organization.

When Authentication Fail URL is set, this property maps reasons for authentication failure to custom messages, as follows:

  • AUTHN_BOOKKEEPING_COOKIE_MISSING: The agent cannot find the authentication tracking cookie. This error can happen if the user successfully authenticates, but clicks the back button of the browser to return to the previous page.

  • NONCE_MISSING: The agent found the authentication tracking cookie, but it cannot find the unique identifier of the authentication request inside the cookie. This error can happen if the user successfully authenticates, but clicks the back button of the browser to return to the previous page.

  • BAD_AUDIENCE: The audience in the JWT did not correspond to the audience in the cookie entry. This error can happen if all agents working in a cluster do not have the same Agent Profile Name.

  • NO_TOKEN: The agent cannot find the session ID token.

  • TOKEN_EXPIRED: The agent found the session ID token, but it is past its expiry date.

  • AM_SAYS_INVALID: The agent found the session ID token, the expiry time is correct, but AM returns that the ID token is invalid.

  • JWT_INVALID: The agent found the session ID token, but cannot parse it.

  • EXCEPTION: The agent found the session ID token, but threw an exception while parsing it. Alternatively, the agent cannot connect to AM to validate the ID token, maybe due to a network outage.

Specify the authentication failure reason from the preceding table as the map key, and your custom error identifier string as the value. For example:

org.forgerock.agents.authn.fail.reason.remapper[TOKEN_EXPIRED]=MY_ERROR_MESSAGE

Consider remapping all the failure reasons to a new error message, then be specific on those that hold more meaning for your environment. For example:

org.forgerock.agents.authn.fail.reason.remapper=ERROR

org.forgerock.agents.authn.fail.reason.remapper[AUTHN_BOOKKEEPING_COOKIE_MISSING]=BACK_BUTTON_PRESSED

org.forgerock.agents.authn.fail.reason.remapper[NONCE_MISSING]=BACK_BUTTON_PRESSED

To map all the authentication failure reasons to the same message, you do not need to specify a key in the property.

Property name

org.forgerock.agents.authn.fail.reason.remapper

Aliases

org.forgerock.agents.authn.fail.reason.remapper
  Introduced in Java Agent 5.7
  Recognized from AM 7

Function

Authentication failure

Type

Map

  • Keys: failed auth reason code

  • Values: masked value

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Authentication Fail Reason Parameter Value Map