Supported Callbacks

The following types of callbacks are available:

Callback Type	Description
Interactive	AM returns these callbacks to request information from the user.
Read-Only	AM uses these callbacks to return information to the client or to show information to the user.
Backchannel	AM uses backchannel callbacks when it needs to recover additional information from the user's request. For example, when it requires a particular header or a certificate.

Interactive Callbacks

AM returns the following callbacks to request information from the user:

ChoiceCallback

Used to display a list of choices and retrieve the selected choice. To indicate that the user selected the first choice, return a value of 0 to AM. For the second choice, return a value of 1, and so forth.

Example

"callbacks":[
   {
      "type":"ChoiceCallback",
      "output":[
         {
            "name":"prompt",
            "value":"Choose one"
         },
         {
            "name":"choices",
            "value":[
               "Choice A",
               "Choice B",
               "Choice C"
            ]
         },
         {
            "name":"defaultChoice",
            "value":2
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":0
         }
      ]
   }
]

Class to import: javax.security.auth.callback.ChoiceCallback

ConfirmationCallback

Used to ask for a boolean-style confirmation, such as yes/no or true/false, and retrieve the response. Also can present a "Cancel" option. To indicate that the user selected the first choice, return a value of 0 to AM. For the second choice, return a value of 1, and so forth.

Example

"callbacks":[
   {
      "type":"ConfirmationCallback",
      "output":[
         {
            "name":"prompt",
            "value":""
         },
         {
            "name":"messageType",
            "value":0
         },
         {
            "name":"options",
            "value":[
               "Submit",
               "Start Over",
               "Cancel"
            ]
         },
         {
            "name":"optionType",
            "value":-1
         },
         {
            "name":"defaultOption",
            "value":1
         }
      ],
      "input":[
         {
            "name":"IDToken2",
            "value":0
         }
      ]
   }
]

Class to import: javax.security.auth.callback.ConfirmationCallback

DeviceProfileCallback

Used to request information about the device being used to authenticate.

Important

The AM XUI user interface does not support this callback.

Support for this callback is provided by:

The ForgeRock SDKs.
The Login UI component of the Platform UI.

The callback may request metadata and/or location information about the device by setting the relevant value to true in the JSON:

Example

"callbacks": [
    {
        "type": "DeviceProfileCallback",
        "output": [
            {
                "name": "metadata",
                "value": true
            },
            {
                "name": "location",
                "value": true
            },
            {
                "name": "message",
                "value": "Collecting....."
            }
        ],
        "input": [
            {
                "name": "IDToken1",
                "value": ""
            }
        ]
    }
]

The callback also contains the message entry, with optional text to display to the user while collecting the information.

The ForgeRock SDKs gather and return the requested information in a JSON abject, as well as the following elements:

identifier: A unique identifier string that can be used to later match the device.
alias: A friendly name for the device, often derived from the make and model.

The response you should return in the callback should include information resembling the following:

Example Callback Response

{
   "identifier":"aec3fe784...o3Xjiizyb9=",
   "alias":"Pixel 3 XL",
   "metadata":{
      "platform":{
         "platform":"Android",
         "version":28,
         "device":"generic_x86_arm",
         "deviceName":"AOSP on IA Emulator",
         "model":"AOSP on IA Emulator",
         "brand":"google",
         "locale":"en_US",
         "timeZone":"America/Vancouver",
         "jailBreakScore":1
      },
      "hardware":{
         "hardware":"ranchu",
         "manufacturer":"Google",
         "storage":774,
         "memory":1494,
         "cpu":4,
         "display":{
            "width":1440,
            "height":2621,
            "orientation":1
         },
         "camera":{
            "numberOfCameras":2
         }
      },
      "browser":{
         "agent":"Dalvik/2.1.0 (Linux; U; Android 9; AOSP on IA Emulator Build/PSR1.180720.117)"
      },
      "bluetooth":{
         "supported":false
      },
      "network":{
         "connected":true
      },
      "telephony":{
         "networkCountryIso":"us",
         "carrierName":"Android"
      }
   },
   "location":{
      "latitude":51.431534,
      "Longitude":-2.622353
   }
 }

The JSON should be escaped and returned in the input/IDToken1 property of the response.

As with all interactive callbacks, you should also return the authId value. See "Returning Callback Information to AM".

NameCallback

Used to retrieve a data string which can be entered by the user. Usually used for collecting user names.

Example

"callbacks":[
   {
      "type":"NameCallback",
      "output":[
         {
            "name":"prompt",
            "value":"User Name"
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":""
         }
      ]
   }
 ]

Class to import: javax.security.auth.callback.NameCallback

PasswordCallback

Used to retrieve a password value.

Example

"callbacks":[
   {
      "type":"PasswordCallback",
      "output":[
         {
            "name":"prompt",
            "value":"Password"
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":""
         }
      ]
   }
]

Class to import: javax.security.auth.callback.PasswordCallback

TextInputCallback

Used to retrieve text input from the end user.

Example

"callbacks":[
   {
      "type":"TextInputCallback",
      "output":[
         {
            "name":"prompt",
            "value":"User Name"
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":""
         }
      ]
   }
]

Class to import: javax.security.auth.callback.TextInputCallback

Read-only Callbacks

AM uses the following callbacks to return information to the client or to show information to the user:

HiddenValueCallback

Used to return form values that are not visually rendered to the end user.

Example

"callbacks":[
   {
      "type":"HiddenValueCallback",
      "output":[
         {
            "name":"value",
            "value":"6186c911-b3be-4dbc-8192-bdf251392072"
         },
         {
            "name":"id",
            "value":"jwt"
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":"jwt"
         }
      ]
   }
]

Class to import: com.sun.identity.authentication.callbacks.HiddenValueCallback

MetadataCallback

Used to inject key-value meta data into the authentication process. For example:

Example

"callbacks":[
   {
      "type":"MetadataCallback",
      "output":[
         {
            "name":"data",
            "value":{
                  "myParameter": "MyValue"
            }
         }
      ]
   }
]

Class to import: com.sun.identity.authentication.spi.MetadataCallback

PollingWaitCallback

Tells the user the amount of time to wait before responding to the callback.

Example

"callbacks":[
   {
      "type":"PollingWaitCallback",
      "output":[
         {
            "name":"waitTime",
            "value":"8000"
         },
         {
            "name":"message",
            "value":"Waiting for response..."
         }
      ]
   }
]

Class to import: org.forgerock.openam.authentication.callbacks.PollingWaitCallback

RedirectCallback

Used to redirect the user's browser or user-agent.

Example

"callbacks":[
   {
      "type":"RedirectCallback",
      "output":[
         {
            "name":"redirectUrl",
            "value":"https://accounts.google.com/o/oauth2/v2/auth?nonce..."
         },
         {
            "name":"redirectMethod",
            "value":"GET"
         },
         {
            "name":"trackingCookie",
            "value":true
         }
      ]
   }
]

Class to import: com.sun.identity.authentication.spi.RedirectCallback

SuspendedTextOutputCallback

Used to display a message to the end user after their authentication tree is suspended.

Example

"callbacks":[
  {
     "type": "SuspendedTextOutputCallback",
     "output": [
       {
           "name": "message",
           "value": "An email has been sent to your inbox."
       },
       {
           "name": "messageType",
           "value": "0"
       }
     ]
  }
]

Class to import: org.forgerock.openam.auth.node.api.SuspendedTextOutputCallback

TextOutputCallback

Used to display a message to the end user.

Example

"callbacks":[
   {
      "type":"TextOutputCallback",
      "output":[
         {
            "name":"message",
            "value":"Default message"
         },
         {
            "name":"messageType",
            "value":"0"
         }
      ]
   }
]

Class to import: javax.security.auth.callback.TextOutputCallback

Backchannel Callbacks

AM uses backchannel callbacks when it needs to recover additional information from the user's request. For example, when it requires a particular header or a certificate.

HttpCallback

Used to access user credentials sent in the Authorization header. For example:

Authorization: Basic bXlDbGllbnQ6Zm9yZ2Vyb2Nr

Class to import: com.sun.identity.authentication.spi.HttpCallback

LanguageCallback

Used to retrieve the locale for localizing text presented to the end user. The locale is sent in the request as a header.

Class to import: javax.security.auth.callback.LanguageCallback

ScriptTextOutputCallback

Used to insert a script into the page presented to the end user. The script can, for example, collect data about the user's environment.

Class to import: com.sun.identity.authentication.callbacks.ScriptTextOutputCallback

X509CertificateCallback

Used to retrieve the content of an x.509 certificate, for example, from a header.

Class to import: com.sun.identity.authentication.spi.X509CertificateCallback