Supported Callbacks
For more information about how to use callbacks to authenticate to AM, see "Returning Callback Information to AM".
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:
- BooleanAttributeInputCallback
On a ForgeRock Identity Platform deployment, this callback is used to ask for a boolean-style confirmation, such as yes/no, or true/false, and retrieve the response.
Differs from the ConfirmationCallback in that the
BooleanAttributeInputCallbackcan be used with IDM policy information to validate the input against the managed user schema. For use examples, see the "Attribute Collector Node".name. A string containing the name of the attribute in the user profile.prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.required. A boolean indicating whether input is required for this attribute.policies. One or more JSON objects describing validation policies that the provided input is required to pass. The object will be empty if validation is disabled in the "Attribute Collector Node".The node collects policy information from IDM. For more information about the policies available by default, see Default Policy for Managed Objects in the Identity Management Object Modeling Guide.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.Requires validation to be enabled in the "Attribute Collector Node".
validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property astruein the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.
Requires validation to be enabled in the "Attribute Collector Node".
value. A string containing a default value for the attribute, if required.
{ "callbacks": [ { "type": "BooleanAttributeInputCallback", "output": [ { "name": "name", "value": "preferences/marketing" }, { "name": "prompt", "value": "Send me special offers and services" }, { "name": "required", "value": true }, { "name": "policies", "value": {} }, { "name": "failedPolicies", "value": [] }, { "name": "validateOnly", "value": false }, { "name": "value", "value": false } ], "input": [ { "name": "IDToken1", "value": false }, { "name": "IDToken1validateOnly", "value": false } ] } ] }Return the value in the callback and the boolean that specifies whether
validateOnlyshould be true.Class to import:
org.forgerock.openam.authentication.callbacks.BooleanAttributeInputCallback- 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
0to 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
0to 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":"IDToken1", "value":0 } ] } ]Class to import:
javax.security.auth.callback.ConfirmationCallback- ConsentMappingCallback
On a ForgeRock Identity Platform deployment, this callback displays managed user attributes that require user consent. It also collects consent from the user.
For more information about requiring consent for attributes, see Configure Privacy and Consent in the Identity Management Self-Service Reference.
{ "callbacks": [ { "type": "ConsentMappingCallback", "output": [ { "name": "name", "value": "managedUser_managedUser" }, { "name": "displayName", "value": "Test Mapping" }, { "name": "icon", "value": "" }, { "name": "accessLevel", "value": "Actual Profile" }, { "name": "isRequired", "value": true }, { "name": "message", "value": "You consent to your data being shared with external services." }, { "name": "fields", "value": [] } ], "input": [ { "name": "IDToken1", "value": false } ] } ] }The user must give consent to all attributes, or to none. Therefore, the input object for this callback is a single boolean value.
Class to import:
org.forgerock.openam.authentication.callbacks.ConsentMappingCallback- DeviceProfileCallback
Used to request information about the device being used to authenticate.
The callback may request
metadataand/orlocationinformation about the device by setting the relevant value totruein 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
messageentry, 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:
identifierA unique identifier string that can be used to later match the device.
aliasA friendly name for the device, often derived from the make and model.
Return an escaped JSON in the input object on the callback. It 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 } }Class to import:
org.forgerock.openam.authentication.callbacks.DeviceProfileCallback- IdPCallback
Provides the information required by a client to authenticate with a social identity provider. Clients, such as an app using the ForgeRock SDK for Android or iOS, can use this information to authenticate to the social identity provider using native APIs and SDKs provided by the mobile OS.
The "Social Provider Handler Node" returns this callback when its Client Type is set to
NATIVE.The response to this callback should be the result of authenticating with the social provider. For example, it might be an OAuth 2.0 or OpenID Connect access or ID token, depending on the provider.
"callbacks": [ { "type": "IdPCallback", "output": [ { "name": "provider", "value": "amazon" }, { "name": "clientId", "value": "amzn1.application-oa2-client.f0c11aa1f8504f8da26a346ccc55a39e" }, { "name": "redirectUri", "value": "https://localhost:8443/openam" }, { "name": "scopes", "value": [ "profile" ] }, { "name": "nonce", "value": "" }, { "name": "acrValues", "value": [] }, { "name": "request", "value": "" }, { "name": "requestUri", "value": "" } ], "input": [ { "name": "IDToken1token", "value": "" }, { "name": "IDToken1token_type", "value": "" } ] } ]Class to import:
org.forgerock.openam.authentication.callbacks.IdPCallback- KbaCreateCallback
On a ForgeRock Identity Platform deployment, this callback collects knowledge-based authentication (KBA) answers to questions predefined in IDM, or lets users register both questions and answers.
For more information about the predefined questions, see Configure Security Questions in the Identity Management Self-Service Reference.
{ "callbacks": [ { "type": "KbaCreateCallback", "output": [ { "name": "prompt", "value": "Select a security question" }, { "name": "predefinedQuestions", "value": [ "What's your favorite color?" ] } ], "input": [ { "name": "IDToken1question", "value": "" }, { "name": "IDToken1answer", "value": "" } ] } ] }Input objects enumerate pairs of questions and answers. When
IDTokennumberquestionis empty, the value returned inIDTokennumberansweris related to the predefined questions. In other words, the answer collected inIDToken1answeris related to the first predefined question, unlessIDToken1questionis collected in as well.Class to import:
org.forgerock.openam.authentication.callbacks.KbaCreateCallback- 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- NumberAttributeInputCallback
On a ForgeRock Identity Platform deployment, this callback collects numerical-only attributes, such as size, or age.
It can be used with IDM policy information to validate the input against the managed user schema. For use examples, see the "Attribute Collector Node".
name. A string containing the name of the attribute in the user profile.prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.required. A boolean indicating whether input is required for this attribute.policies. One or more JSON objects describing validation policies that the provided input is required to pass. The object will be empty if validation is disabled in the "Attribute Collector Node".The node collects policy information from IDM. For more information about the policies available by default, see Default Policy for Managed Objects in the Identity Management Object Modeling Guide.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.Requires validation to be enabled in the "Attribute Collector Node".
validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property astruein the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.
Requires validation to be enabled in the "Attribute Collector Node".
value. A string containing a default value for the attribute, if required.
Return the numeric value in the callback and the boolean that specifies whether
validateOnlyshould be true.Class to import:
org.forgerock.openam.authentication.callbacks.NumberAttributeInputCallback- 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- SelectIdPCallback
Offers a choice of social identity provider, or local authentication.
The Select Identity Provider node returns this callback when one or more social identity providers are enabled, or a single provider is enabled as well as the Local Authentication option, and therefore a choice from the user is required.
The response to this callback should be the name of the provider; for example
amazon, orlocalAuthentication, if the user wants to authenticate without using a social provider."callbacks": [ { "type": "SelectIdPCallback", "output": [ { "name": "providers", "value": [ { "provider": "amazon", "uiConfig": { "buttonCustomStyle": "background: linear-gradient(to bottom, #f7e09f 15%,#f5c646 85%);color: black;border-color: #b48c24;", "buttonImage": "", "buttonClass": "fa-amazon", "buttonDisplayName": "Amazon", "buttonCustomStyleHover": "background: linear-gradient(to bottom, #f6c94e 15%,#f6c94e 85%);color: black;border-color: #b48c24;", "iconClass": "fa-amazon", "iconFontColor": "black", "iconBackground": "#f0c14b" } }, { "provider": "google", "uiConfig": { "buttonImage": "images/g-logo.png", "buttonCustomStyle": "background-color: #fff; color: #757575; border-color: #ddd;", "buttonClass": "", "buttonCustomStyleHover": "color: #6d6d6d; background-color: #eee; border-color: #ccc;", "buttonDisplayName": "Google", "iconFontColor": "white", "iconClass": "fa-google", "iconBackground": "#4184f3" } }, { "provider": "localAuthentication" } ] }, { "name": "value", "value": "" } ], "input": [ { "name": "IDToken1", "value": "" } ] } ]Class to import:
org.forgerock.openam.authentication.callbacks.SelectIdPCallback- StringAttributeInputCallback
On a ForgeRock Identity Platform deployment, this callback collects string attributes, such as city names, telephone numbers, and postcodes.
Differs from the TextInputCallback in that the
StringAttributeInputCallbackcan be used to validate the input against the managed user schema policies. For use examples, see the "Attribute Collector Node".name. A string containing the name of the attribute in the user profile.prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.required. A boolean indicating whether input is required for this attribute.policies. One or more JSON objects describing validation policies that the provided input is required to pass. The object will be empty if validation is disabled in the "Attribute Collector Node".The node collects policy information from IDM. For more information about the policies available by default, see Default Policy for Managed Objects in the Identity Management Object Modeling Guide.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.Requires validation to be enabled in the "Attribute Collector Node".
validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property astruein the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.
Requires validation to be enabled in the "Attribute Collector Node".
value. A string containing a default value for the attribute, if required.
{ "callbacks": [ { "type": "StringAttributeInputCallback", "output": [ { "name": "name", "value": "givenName" }, { "name": "prompt", "value": "First Name" }, { "name": "required", "value": true }, { "name": "policies", "value": { "policyRequirements": [ "REQUIRED", "VALID_TYPE" ], "fallbackPolicies": null, "name": "givenName", "policies": [ { "policyRequirements": [ "REQUIRED" ], "policyId": "required" }, { "policyRequirements": [ "VALID_TYPE" ], "policyId": "valid-type", "params": { "types": [ "string" ] } } ], "conditionalPolicies": null } }, { "name": "failedPolicies", "value": [] }, { "name": "validateOnly", "value": false }, { "name": "value", "value": "" } ], "input": [ { "name": "IDToken1", "value": "" }, { "name": "IDToken1validateOnly", "value": false } ] } ] }The following example shows the value of the policy object when input validation is not required:
... { "name": "policies", "value": {} }, ...Return the string value in the callback and the boolean that specifies whether
validateOnlyshould be true.Class to import:
org.forgerock.openam.authentication.callbacks.StringAttributeInputCallback- TermsAndConditionsCallback
On a ForgeRock Identity Platform deployment, this callback shows the company's terms and conditions, and collects the user's agreement to them.
To configure the terms and conditions text, see Terms and Conditions in the Identity Management Self-Service Reference.
{ "callbacks": [ { "type": "TermsAndConditionsCallback", "output": [ { "name": "version", "value": "0.0" }, { "name": "terms", "value": "Terms and conditions text that customers must agree to." }, { "name": "createDate", "value": "2019-10-28T04:20:11.320Z" } ], "input": [ { "name": "IDToken1", "value": false } ] } ] }The input object for this callback is a boolean that specifies whether the user agrees to the terms and conditions.
Class to import:
org.forgerock.openam.authentication.callbacks.TermsAndConditionsCallback- TextInputCallback
Used to retrieve text input from the end user.
"callbacks":[ { "type":"TextInputCallback", "output":[ { "name":"prompt", "value":"Provide a nickname for this account" } ], "input":[ { "name":"IDToken1", "value":"" } ] } ]Class to import:
javax.security.auth.callback.TextInputCallback- ValidatedCreatePasswordCallback
On a ForgeRock Identity Platform deployment, this callback is used to collect a password value.
Differs from the PasswordCallback in that the
ValidatedCreatePasswordCallbackvalidates the input against the managed user schema policies. For use examples, see the "Platform Password Node".name. A string containing the name of the attribute in the user profile.policies. One or more JSON objects describing validation policies that the provided input is required to pass.The node collects policy information from IDM. For more information about the policies available by default, see Default Policy for Managed Objects.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property astruein the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.
prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.
{ "callbacks": [ { "type": "ValidatedCreatePasswordCallback", "output": [ { "name": "echoOn", "value": false }, { "name": "policies", "value": { "policyRequirements": [ "VALID_TYPE", "MIN_LENGTH", "AT_LEAST_X_CAPITAL_LETTERS", "AT_LEAST_X_NUMBERS", "CANNOT_CONTAIN_OTHERS" ], "fallbackPolicies": null, "name": "password", "policies": [ { "policyRequirements": [ "VALID_TYPE" ], "policyId": "valid-type", "params": { "types": [ "string" ] } }, { "policyId": "minimum-length", "params": { "minLength": 8 }, "policyRequirements": [ "MIN_LENGTH" ] }, { "policyId": "at-least-X-capitals", "params": { "numCaps": 1 }, "policyRequirements": [ "AT_LEAST_X_CAPITAL_LETTERS" ] }, { "policyId": "at-least-X-numbers", "params": { "numNums": 1 }, "policyRequirements": [ "AT_LEAST_X_NUMBERS" ] }, { "policyId": "cannot-contain-others", "params": { "disallowedFields": [ "userName", "givenName", "sn" ] }, "policyRequirements": [ "CANNOT_CONTAIN_OTHERS" ] } ], "conditionalPolicies": null } }, { "name": "failedPolicies", "value": [] }, { "name": "validateOnly", "value": false }, { "name": "prompt", "value": "Password" } ], "input": [ { "name": "IDToken1", "value": "" }, { "name": "IDToken1validateOnly", "value": false } ] } ] }Return the password value in the callback and the boolean that specifies whether
validateOnlyshould be true.Class to import:
org.forgerock.openam.authentication.callbacks.ValidatedCreatePasswordCallback- ValidatedCreateUsernameCallback
On a ForgeRock Identity Platform deployment, this callback is used to collect user name strings.
Differs from the NameCallback in that the
ValidatedCreateUsernameCallbackvalidates the input against the managed user schema policies. For use examples, see the "Platform Username Node".name. A string containing the name of the attribute in the user profile.policies. One or more JSON objects describing validation policies that the provided input is required to pass.The node collects policy information from IDM. For more information about the policies available by default, see Default Policy for Managed Objects.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property astruein the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.
prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.
{ "callbacks": [ { "type": "ValidatedCreateUsernameCallback", "output": [ { "name": "policies", "value": { "policyRequirements": [ "REQUIRED", "VALID_TYPE", "VALID_USERNAME", "CANNOT_CONTAIN_CHARACTERS", "MIN_LENGTH", "MAX_LENGTH" ], "fallbackPolicies": null, "name": "userName", "policies": [ { "policyRequirements": [ "REQUIRED" ], "policyId": "required" }, { "policyRequirements": [ "VALID_TYPE" ], "policyId": "valid-type", "params": { "types": [ "string" ] } }, { "policyId": "valid-username", "policyRequirements": [ "VALID_USERNAME" ] }, { "policyId": "cannot-contain-characters", "params": { "forbiddenChars": [ "/" ] }, "policyRequirements": [ "CANNOT_CONTAIN_CHARACTERS" ] }, { "policyId": "minimum-length", "params": { "minLength": 1 }, "policyRequirements": [ "MIN_LENGTH" ] }, { "policyId": "maximum-length", "params": { "maxLength": 255 }, "policyRequirements": [ "MAX_LENGTH" ] } ], "conditionalPolicies": null } }, { "name": "failedPolicies", "value": [] }, { "name": "validateOnly", "value": false }, { "name": "prompt", "value": "Username" } ], "input": [ { "name": "IDToken1", "value": "" }, { "name": "IDToken1validateOnly", "value": false } ] } ] }Return the user name in the callback and the boolean that specifies whether
validateOnlyshould be true.Class to import:
org.forgerock.openam.authentication.callbacks.ValidatedCreateUsernameCallback
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.
For example, the Social Provider Handler node returns this callback when its Client Type is set to
BROWSER, and the client needs to redirect the user to a social identity provider for authentication."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