Authentication nodes

Set Failure Details node

The Set Failure Details node adds details to the JSON response when a journey ends in failure. You can configure the node properties to:

  • Return a failure message.

  • Include extra information in the response body in the form of static key:value fields.

  • Set custom response headers. RAPID only

    You can’t modify the protected HTTP headers, nor can you modify the session cookie or load balancer cookie using the Set-Cookie header.

    Protected HTTP headers

    • X-Frame-Options

    • X-Content-Type-Options

    • Cache-Control

    • Content-API-Version

    • Expires

    • Pragma

    • Content-Type

    • Content-Length

    • Date

    • Keep-Alive

    • Connection

    • Transfer-Encoding

    • Server

    • Trailer

    • Upgrade

Examples

Example 1: Add a failure message and details on account lockout

This example uses the Set Failure Details node and assumes the following configuration:

Failure Message

  • Key: en-gb

  • Value: Your account is locked

Failure Details

  • Key: Reason

  • Value: Exceeded max retries

Journey with a Set Failure Details node

  • The Page node containing the Platform Username node and Platform Password node prompts for credentials.

  • The Data Store Decision node validates the username-password credentials.

  • If authentication is successful:

  • If authentication fails:

    • The Retry Limit Decision node checks the number of failed authentications against the configured limit. If the retry limit is reached, the journey continues on the Reject outcome path.

    • The Account Lockout node locks the account.

    • The Set Failure Details node displays the configured message to the user and adds both the message and the details to the JSON response.

      For example:

      {
  "code":401,
  "reason":"Unauthorized",
  "message":"Your account is locked",
  "detail":{
    "Reason":"Exceeded max retries"
  }
}

Example 2: Set custom response headers

RAPID only

This example uses the Set Failure Details node to set a Custom-Fail response header when the journey ends in failure after locking the user’s account. This header could be read by a custom UI to trigger a specific action when the user’s account is locked.

Journey with a Set Failure Details node to set custom response headers

Follow these steps to try the example:

  1. Create the example journey using the journey editor.

  2. Authenticate a test user with the journey using incorrect credentials. Make sure you include the --show-headers option (or --include in older curl versions) to return the response headers:

    $ curl --show-headers \
--request POST \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: wrong-password' \
--header "Accept-API-Version: resource=2.1, protocol=1.0" \
"https://tenant-env-fqdn/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=myJourney"

HTTP/1.1 401
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
...
Custom-Fail: account-locked
...

{
    "code":401,
    "reason":"Unauthorized",
    "message":"Login failure"
}

Availability

Product Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

None. This node doesn’t read shared state data.

Dependencies

None.

Configuration

Property Usage

Failure Message

The message to add to the JSON response when authentication fails:

Add a custom, localized message per locale:

  1. Click .

  2. In the Key field, enter the locale. For example, en-gb.1

  3. In the Value field, enter the message. For example, Your account has been locked.

  4. Click Done.

  5. Repeat to add more messages and save your changes when you’re done.

Failure Details

The details to add to the JSON response on journey failure:

  1. Click .

  2. In the Key field, enter a name to identify the details. For example, Reason.

  3. In the Value field, enter the details to return. For example, Exceeded max retries.

    The value can be a simple text string, a boolean value, or a JSON formatted value. The value is formatted appropriately when output in the JSON response.

    For example:

    Key Value Output

    example

    this is a test value

    		 
    "example": "this is a test value"

    boolean

    true

    		 
    "boolean": true

    field

    { "nested": "nested value" }

    		 
    "field": {
   "nested": "nested value"
}

  4. Click Done.

  5. Click Add to repeat and add more details.

  6. Save your changes.

Response Headers RAPID only

The response headers to set:

  • To add a response header:

    1. Click Add in the Response Headers modal.

    2. Enter the HTTP header name to display in the Key field and the corresponding value to display in the Value field.

    3. Click Done.

  • To edit a response header:

    1. Click the Pencil icon ().

    2. Update the Key and Value as when adding headers.

  • To remove a response header, click the Delete icon ().

When finished, click Save to keep your settings.

(1) Specify a locale that Java supports, such as en-gb. Otherwise, the node throws a configuration exception with an Invalid locale provided message.

Outputs

This node doesn’t change the shared state.

Callbacks

This node doesn’t send any callbacks.

Outcomes

Single outcome path: when the journey ends in failure, this node adds the configured details to the JSON response.

Errors

This node doesn’t log any error or warning messages of its own.