--- title: Interactive callbacks description: Nodes return the following callbacks to request information. component: pingam version: 7.3 page_id: pingam:authentication-guide:authn-interactive-callbacks canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/callbacks-interactive.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Authentication", "Callbacks", "Setup & Configuration"] section_ids: BooleanAttributeInputCallback: BooleanAttributeInputCallback ChoiceCallback: ChoiceCallback ConfirmationCallback: ConfirmationCallback ConsentMappingCallback: ConsentMappingCallback DeviceProfileCallback: DeviceProfileCallback hiddenvaluecallback: HiddenValueCallback IdPCallback: IdPCallback KbaCreateCallback: KbaCreateCallback NameCallback: NameCallback NumberAttributeInputCallback: NumberAttributeInputCallback PasswordCallback: PasswordCallback SelectIdPCallback: SelectIdPCallback StringAttributeInputCallback: StringAttributeInputCallback TermsAndConditionsCallback: TermsAndConditionsCallback TextInputCallback: TextInputCallback ValidatedCreatePasswordCallback: ValidatedCreatePasswordCallback ValidatedCreateUsernameCallback: ValidatedCreateUsernameCallback --- # Interactive callbacks Nodes return the following callbacks to request information. ## BooleanAttributeInputCallback Collects a boolean-style confirmation, such as yes/no or true/false. The [Attribute Collector node](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-attribute-collector.html) uses this instead of a [ConfirmationCallback](#ConfirmationCallback) to apply IDM policies and validate the response. | Callback output field | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `failedPolicies` | An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. | | `name` | A string containing the name of the attribute in the user profile. | | `policies` | An array of JSON objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.The node collects policy information from IDM. For more information about the policies available by default, refer to [Default policy for managed objects](https://docs.pingidentity.com/pingidm/7.3/objects-guide/configuring-default-policy.html) in the IDM documentation. | | `prompt` | A string containing the description of the information required from the user. | | `required` | A boolean indicating whether input is required for this attribute. | | `validateOnly` | When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When `true`, the node only performs input validation and does not continue to the next node.When `true`, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next node. | | `value` | A string containing a default value for the attribute, if required. | Example ```json { "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 }] }] } ``` In the input, return the value and a boolean to set `validateOnly`. * Class to import `org.forgerock.openam.authentication.callbacks.BooleanAttributeInputCallback` ## ChoiceCallback Provides a list of choices and collects the selected choice. In the input, return `0` if the user selected the first choice, `1` for the second choice, and so forth. Example ```json { "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 Collects a boolean-style confirmation, such as yes/no or true/false with an optional "Cancel" choice. | Callback output field | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `defaultOption` | A number identifying the default option in the array of `options`, counting from `0`. | | `messageType` | A number indicating the severity of the message:- `0`: Information - `1`: Warning - `2`: Error | | `optionType` | A number indicating the type of confirmation:- `-1`: Unspecified - `0`: Yes/no - `1`: Yes/no/cancel - `2`: OK/cancel | | `options` | An array of strings containing the option text for display to the user. | | `prompt` | A string containing the description of the choice to display to the user. | Example ```json { "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 }] }] } ``` In the input, return `0` if the user selected the first choice, `1` for the second choice, and so forth. * Class to import `javax.security.auth.callback.ConfirmationCallback` ## ConsentMappingCallback Provides profile attributes that require user consent and collects consent from the user. | Callback output field | Description | | --------------------- | ----------------------------------------------------------------------------- | | `accessLevel` | A string containing the access level description for display to the user. | | `displayName` | A string containing the name for display to the user. | | `fields` | An array containing names of the attributes to share. | | `icon` | A string containing an icon specification for the privacy and consent notice. | | `isRequired` | A boolean indicating whether consent is required. | | `message` | A string containing the privacy and consent notice for display to the user. | | `name` | A string containing the name of the mapping. | Example ```json { "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; in the input, return a single boolean value. * Class to import `org.forgerock.openam.authentication.callbacks.ConsentMappingCallback` ## DeviceProfileCallback Collects information about the device used to authenticate. | Callback output field | Description | | --------------------- | --------------------------------------------------------------------------------- | | `metadata` | A boolean indicating whether to collect device metadata. | | `location` | A boolean indicating whether to collect the device location. | | `message` | A string containing optional text to display while collecting device information. | Example ```json { "callbacks": [{ "type": "DeviceProfileCallback", "output": [{ "name": "metadata", "value": true }, { "name": "location", "value": true }, { "name": "message", "value": "Collecting....." }], "input": [{ "name": "IDToken1", "value": "" }] }] } ``` In the input, return escaped JSON resembling the following example response data. Example response data ```json { "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 `location` and `metadata` fields are required when their values are `true` in the output. The `alias` and `identifier` fields are optional and provided when the client uses the ForgeRock SDKs. * `alias` A friendly name for the device often derived from the make and model. * `identifier` A unique identifier string that can be used to later match the device. * `location` Latitude and longitude of the device. * `metadata` Refer to the example response data for details. * Class to import `org.forgerock.openam.authentication.callbacks.DeviceProfileCallback` ## HiddenValueCallback Provides form values that are to remain hidden from the user. Example ```json { "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` ## IdPCallback Collects the result of a native OAuth 2.0 or OpenID Connect request to a social identity provider. The [Social Provider Handler node](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-social-provider-handler.html) returns this callback when its Client Type is set to `NATIVE`. The output provides the information required to perform the request. Clients built using the ForgeRock SDK for Android or iOS use this to authenticate to the social identity provider with the mobile OS native APIs. | Callback output field | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `acrValues` | An array containing the Authentication Context Class Reference values for the native authentication request. | | `clientId` | A string containing the identifier for the native authentication request. | | `nonce` | A string containing the nonce for the native authentication request. | | `provider` | A string containing a name for the provider. | | `redirectUri` | A string containing the redirection URI for the native authentication request. | | `request` | A string containing the Request Object for the native authentication request. | | `requestUri` | A string containing a URL that references a resource containing the Request Object for the native authentication request. | | `scopes` | An array containing the scopes for the native authentication request. | Example ```json { "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": "" }] }] } ``` In the input, return a JWT `id_token`, `access_token` or authorization code for the token, and `id_token`, `access_token` or `authorization_code` for the token type. * Class to import `org.forgerock.openam.authentication.callbacks.IdPCallback` ## KbaCreateCallback Collects knowledge-based authentication (KBA) answers to questions defined in the user profile, or user-defined question and answer pairs. Example ```json { "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": "" }] }] } ``` In the input, return an empty `IDTokenNumberquestion` value when `IDTokenNumberanswer` corresponds to `predefinedQuestions[Number]`. For user-provided questions, return both. * Class to import `org.forgerock.openam.authentication.callbacks.KbaCreateCallback` ## NameCallback Collects a string entered by the user, such as a username. Example ```json { "callbacks": [{ "type": "NameCallback", "output": [{ "name": "prompt", "value": "User Name" }], "input": [{ "name": "IDToken1", "value": "" }] }] } ``` * Class to import `javax.security.auth.callback.NameCallback` ## NumberAttributeInputCallback Collects a numeric attribute, such as size or age. The [Attribute Collector node](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-attribute-collector.html) uses this to apply IDM policies and validate the response. | Callback output field | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `failedPolicies` | An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. | | `name` | A string containing the name of the attribute in the user profile. | | `policies` | An array of JSON objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.The node collects policy information from IDM. For more information about the policies available by default, refer to [Default policy for managed objects](https://docs.pingidentity.com/pingidm/7.3/objects-guide/configuring-default-policy.html) in the IDM documentation. | | `prompt` | A string containing the description of the information required from the user. | | `required` | A boolean indicating whether input is required for this attribute. | | `validateOnly` | When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When `true`, the node only performs input validation and does not continue to the next node.When `true`, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next node. | | `value` | A string containing a default value for the attribute, if required. | In the input, return the value and a boolean to set `validateOnly`. * Class to import `org.forgerock.openam.authentication.callbacks.NumberAttributeInputCallback` ## PasswordCallback Collects a password value. Example ```json { "callbacks": [{ "type": "PasswordCallback", "output": [{ "name": "prompt", "value": "Password" }], "input": [{ "name": "IDToken1", "value": "" }] }] } ``` * Class to import `javax.security.auth.callback.PasswordCallback` ## SelectIdPCallback Collects a choice of an enabled social identity provider or local authentication. The [Select Identity Provider node](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-select-identity-provider.html) returns this callback when multiple social identity providers are enabled, or when Local Authentication is enabled alongside at least one provider. In the input, return the provider name, such as `amazon` or `localAuthentication`. Example ```json { "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 Collects string attributes, such as city names, telephone numbers, and postcodes. The [Attribute Collector node](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-attribute-collector.html) uses this instead of a [TextInputCallback](#TextInputCallback) to apply IDM policies and validate the response. | Callback output field | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `failedPolicies` | An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. | | `name` | A string containing the name of the attribute in the user profile. | | `policies` | An array of JSON objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.The node collects policy information from IDM. For more information about the policies available by default, refer to [Default policy for managed objects](https://docs.pingidentity.com/pingidm/7.3/objects-guide/configuring-default-policy.html) in the IDM documentation. | | `prompt` | A string containing the description of the information required from the user. | | `required` | A boolean indicating whether input is required for this attribute. | | `validateOnly` | When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When `true`, the node only performs input validation and does not continue to the next node.When `true`, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next node. | | `value` | A string containing a default value for the attribute, if required. | Example ```json { "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 }] }] } ``` When input validation is not required, the `policies` contain an empty object: ```json { "name": "policies", "value": {} } ``` In the input, return the value and a boolean to set `validateOnly`. * Class to import `org.forgerock.openam.authentication.callbacks.StringAttributeInputCallback` ## TermsAndConditionsCallback Displays the current terms and conditions and collects the user's agreement to them. Example ```json { "callbacks": [ { "type": "TermsAndConditionsCallback", "output": [ { "name": "version", "value": "0.0" }, { "name": "terms", "value": "Terms and conditions text that you must agree to." }, { "name": "createDate", "value": "2022-10-28T04:20:11.320Z" } ], "input": [ { "name": "IDToken1", "value": false } ] } ] } ``` In the input, return `true` if the user agrees to the terms and conditions. * Class to import `org.forgerock.openam.authentication.callbacks.TermsAndConditionsCallback` ## TextInputCallback Collects text input from the user. Example ```json { "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 Collects a password value. The [Platform Password node](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-platform-password.html) uses this instead of a [PasswordCallback](#PasswordCallback) to apply IDM policies and validate the response. | Callback output field | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `failedPolicies` | An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. | | `name` | A string containing the name of the attribute in the user profile. | | `policies` | An array of objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.The node collects policy information from IDM. For more information about the policies available by default, refer to [Default policy for managed objects](https://docs.pingidentity.com/pingidm/7.3/objects-guide/configuring-default-policy.html) in the IDM documentation. | | `prompt` | A string containing the description of the information required from the user. | | `validateOnly` | When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When `true`, the node only performs input validation and does not continue to the next node.When `true`, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next node. | Example ```json { "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 }] }] } ``` In the input, return the value and a boolean to set `validateOnly`. * Class to import `org.forgerock.openam.authentication.callbacks.ValidatedPasswordCallback` ## ValidatedCreateUsernameCallback Collects a username. The [Platform Username node](https://docs.pingidentity.com/auth-node-ref/7.3/auth-node-platform-username.html) uses this instead of a [NameCallback](#NameCallback) to apply IDM policies and validate the response. | Callback output field | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `failedPolicies` | An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. | | `name` | A string containing the name of the attribute in the user profile. | | `policies` | An array of objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.The node collects policy information from IDM. For more information about the policies available by default, refer to [Default policy for managed objects](https://docs.pingidentity.com/pingidm/7.3/objects-guide/configuring-default-policy.html) in the IDM documentation. | | `prompt` | A string containing the description of the information required from the user. | | `validateOnly` | When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When `true`, the node only performs input validation and does not continue to the next node.When `true`, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next node. | Example ```json { "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 }] }] } ``` In the input, return the value and a boolean to set `validateOnly`. * Class to import `org.forgerock.openam.authentication.callbacks.ValidatedUsernameCallback`