Supported Callbacks
The following types of callbacks are available:
Callback Type | Description |
---|---|
AM returns these callbacks to request information from the user. | |
AM uses these callbacks to return information to the client or to show information to the user. | |
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 of1
, and so forth."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 of1
, and so forth."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/orlocation
information about the device by setting the relevant value totrue
in the JSON:"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:
{ "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.
"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.
"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.
"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.
"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:
"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.
"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.
"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.
"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.
"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