Authentication prebuilt component

The authentication prebuilt component collects information from the user to authenticate them to the required authentication level. This component covers authentication requirements which are common, but not exclusive, to the financial services (FSI) industry. This component uses the Credit card expiration date collection, Date of birth collection, and Telephone number collection prebuilt components to collect and validate user details.

Authentication levels

There are multiple levels of authentication required by different prebuilt components, with higher levels requiring more user information to authenticate the user. The Authentication component allows users to authenticate to Level 0 (ANI Match), Level 1 (Basic), or Level 2 (Multi-factor) as described in the Authentication Level table.

Authentication Level Requirements
Level 0: ANI Match User is authenticated by calling from or providing a phone number that corresponds to a registered account.

A user can be authenticated to Level 0 by using the Greeting prebuilt component.
Level 1: Basic User is authenticated by verifying a one-time password (OTP) code sent to their email or phone number. If OTP verification fails, user can provide answers to three out of four security questions in order to authenticate successfully: date of birth (DOB), last four digits of the user's debit card or credit card expiration date (depending on whether they are an account or card holder), last transaction amount, and last credit card bill payment method.
Level 2: Multi-factor User is additionally authenticated by verifying a security key generated by an external authenticator app or push notification.

Supported user types

The authentication component provides support for users who are enrolled bank customers who are account holders, card holders, or both. The component also supports authentication for users who are not enrolled bank customers but who have power of attorney for accounts registered with the bank. Users may have one or more accounts or cards registered with the bank.

Authentication types

This component lets you configure whether a user should be authenticated as an account holder, a card holder, or both. These options are configured by setting the $session.params.account_auth_enabled and $session.params.card_auth_enabled input parameters. This table describes the component behavior for different combinations of values for the account authentication and card authentication flags.

account_auth_enabled card_auth_enabled Authentication type
true false The user will be authenticated as an account holder, verifying that the user holds one or more accounts with the bank and confirming security questions including the last four digits of the registered debit card.
false true The user will be authenticated as a card holder, verifying that the user holds one or more credit cards with the bank and confirming security questions including credit card expiration date for a registered credit card.
true true The component first checks whether the user is a registered account holder. If the user holds one or more accounts with the bank, the component authenticates the user using account information. If the user does not hold any accounts with the bank, the component attempts to authenticate the user using cardholder information.
false false The component first checks whether the user is a registered account holder. If the user holds one or more accounts with the bank, the component authenticates the user to Level 0 authentication. If the user does not hold any accounts with the bank, the component checks whether the user is a cardholder. If the user holds one or more credit cards with the bank, the component authenticates the user to Level 0 authentication.

Limitations

In addition to the common prebuilt component limitations, this prebuilt component has the following limitations:

  • OTPs will only be sent to a mobile number or email address previously registered to the user. The component won't use OTP to authenticate customers calling from an alternate phone number that is not registered with their account. When a user calls from an alternate phone number, security questions will be used to authenticate the caller.
  • This component does not encrypt any data.

Sample dialogs

The following sample dialogs demonstrate common scenarios handled by this prebuilt component. The sample dialogs demonstrate behavior when the component is called using telephony, which triggers the Default Welcome Intent and the first agent response at the start of the conversation.

Level 1 authentication success: OTP

User has previously been authenticated to Level 0 authentication. Component sends and asks user to confirm an OTP sent to the channel of the user's choice. User is able to provide a valid OTP and is successfully authenticated to Level 1.

User input Agent response
For security purposes, we need to validate your identity, so we will send you a code. Do you prefer to receive the code by phone or by email?
Phone
We have sent a code to your registered phone number ending in 0000. This may take a few seconds. Can you please confirm the code?
The code is 123457
Thank you, you have been successfully authenticated.

Level 1 authentication success: security questions

Component confirms user's Level 0 authentication by collecting and verifying the provided phone number. Component asks for and validates user's correct answers to three security questions - date of birth, last four digits of user's debit card number, and last transaction amount. User is successfully authenticated to Level 1.

User input Agent response
Are you a customer of our bank, or do you have power of attorney? Please confirm by saying yes or no.
Yes
Okay, we need to collect your phone number to fetch your account details.
Agent collects user's telephone number using Telephone number collection prebuilt component
Got it. The number you mentioned is plus 1 6502530000, is that correct?
Yes
Great, we are done collecting the telephone number.
Okay, for security purposes we will need some more information to validate your identity.
Agent collects user's date of birth using Date of birth collection prebuilt component
Okay, your birthdate is February 3, 1995, is that correct?
Yes
Great, we have collected your birthdate.
Please tell us the last four digits of your debit card number.
It's 1234
Please tell us the dollar amount of your last transaction. For example, if your last transaction amount was $100.30, say "100".
It was 500 dollars
Thank you, you have been successfully authenticated.

Level 2 authentication success: two-factor authentication

User has previously been authenticated to Level 1 authentication. The component asks the user to generate a security key using their bank or authenticator app. User successfully confirms the generated security key and is authenticated to Level 2.

User input Agent response
Please share your security key.
Generate the 6 digit security key in your bank app or authenticator app. Then say or enter the digits.
232425
Thank you, you have been successfully authenticated.

Denial of information

User declines to provide information required to authenticate. The component exits with a failure message.

User input Agent response
For security purposes, we need to validate your identity, so we will send you a code. Do you prefer to receive the code by phone or by email?
No, I don't want to share
Okay, for security purposes we will need some more information to validate your identity.
Agent collects user's date of birth using Date of birth collection prebuilt component
Okay, your birthdate is February 3, 1995, is that correct?
Yes
Great, we have collected your birthdate.
Please tell us the last four digits of your debit card number.
It's 1234
Please tell us the dollar amount of your last transaction. For example, if your last transaction amount was $100.30, say "100".
I don't want to share the details
We weren't able to authenticate you, so we are unable to complete this action. We apologize for any inconvenience caused.

Naming conventions

This prebuilt component uses the following naming conventions:

Feature Format Example
Flow [Component Name] Authentication
Component Specific Intent prebuilt_components_[component_name]_[intent_name] prebuilt_components_authentication_power_of_attorney
Entity Type prebuilt_components_[component_name]_[entity_type] prebuilt_components_authentication_payment_mode
Webhook prebuilt_components_[component_name]:[webhook_action] prebuilt_components_authentication:telephony_verification

Input parameters

Input parameters are parameters that are used to configure certain behaviors of the component. The parameters will be used by one or more conditions within the flow to determine how the component should behave. Flow-scoped parameters must be set on the start page of the component as described below. Session-scoped parameters may be set either by a calling flow, or on the start page of this component.

This prebuilt component accepts the following input parameters:

Parameter Name Description Input Format
$session.params.auth_level (optional) Indicates the current authentication level of the end-user. integer
$session.params.auth_level_req Defines the authentication level the end-user will be authenticated to. Valid values are 0, 1, or 2. integer
$session.params.account_auth_enabled Indicates whether the user should be authenticated as an account holder. The component behavior is dependent on this value and the value of $session.params.card_auth_enabled as described in Authentication levels. boolean
$session.params.card_auth_enabled Indicates whether the user should be authenticated as a card holder. The component behavior is dependent on this value and the value of $session.params.account_auth_enabled as described in Authentication levels. boolean
$session.params.phone_number (optional) End-user's phone number. If this parameter is not provided, the component will collect the phone number from the end-user. string
$flow.max_retry_telephone_counter Specifies the number of retries allowed when collecting the user's telephone number. The default value is 1. integer
$flow.max_retry_security_ans_count Specifies the number of retries allowed when collecting security answers. The default value is 3. integer
$flow.max_retry_security_key Specifies the number of retries allowed when collecting the security key. The default value is 3. integer
$flow.max_retry_otp_not_received Specifies the number of retries allowed when the One Time Password (OTP) is not received. The default value is 1. integer
$flow.max_retry_otp_count Specifies the number of retries allowed when collecting the One Time Password (OTP). The default value is 3. integer
$flow.security_ans_denial_count Specifies the number of retries allowed when a user declines to provide the requested information. The default value is 1. integer
$flow.security_ans_mid_count Specifies the number of incorrect security answers that a user can provide. The default value is 2, which means that if the caller provides incorrect answers to two different questions, the component exits with failure. integer
$flow.max_retry_card_counter Specifies the number of retries allowed when collecting the last four digits of the end-user's debit card. The default value is 2. integer
$flow.security_key_length Specifies the valid length of the security key provided by the authenticator app for Level 2 authentication. The default value is 6. integer
$flow.otp_length Specifies the valid length of the One Time Password (OTP) for Level 1 authentication. The default value is 6. integer

To configure the input parameters for this component, expand for instructions.

  1. Open the Dialogflow CX console.
  2. Choose your Google Cloud project.
  3. Select your agent.
  4. Select the Build tab.
  5. Click the imported component in the Flows section.
  6. Click the Start Page in the Pages section.
  7. Click the true Route in the Start Page.
  8. In the Route window, edit the Parameter Presets values as needed.
  9. Click Save.

Output parameters

Output parameters are session parameters that will remain active after exiting the component. These parameters contain important information collected by the component. This prebuilt component provides values for the following output parameters:

Parameter Name Description Output Format
auth_level Indicates the current authentication level of the end-user. integer
phone_number User's local phone number, without the country code, used to identify the user. string
transfer_reason This parameter indicates the reason the flow exited, if it was not successful. The returned value is one of:

agent: the end-user requested a human agent at some point during the conversation.

denial_of_information: the end-user declined to share information requested by the component.

max_no_input: the conversation reached the maximum number of retries for no-input events. See no-input built-in events.

max_no_match: the conversation reached the maximum number of retries for no-match events. See no-match built-in events.

webhook_error: a webhook error occurred. See webhook.error built-in event.

webhook_not_found: a webhook URL was unreachable. See webhook.error.not-found built-in event.
string

Basic setup

To set up this prebuilt component:

  1. Import the prebuilt component.
  2. Configure the provided flexible webhooks with configuration describing your external services, see Webhook setup below.

Webhook setup

In order to use this component, you will need to configure the included flexible webhooks to retrieve needed information from your external services.

Telephony verification

The prebuilt_components_authentication:telephony_verification webhook is used by the component to fetch user account details based on the provided telephone number.

API request parameters

The following parameters are provided by the component as inputs to the API request.

Parameter Name Description Input Format
$session.params.phone_number User's local phone number, without the country code, used to identify the user. string

API response parameters

The following parameters are pulled from the API response to be used by the component.

Parameter Name Description Output Format
account_count The number of accounts associated with the registered telephone number. These accounts include self-accounts and accounts for which the user has power of attorney. integer
last_four_digit_of_account_number If a user has a single account, the last four digits of the account number are returned. If a user has more than one account, the value of this parameter is null. string
email The email registered with the account. If there is no email registered with the account, the value of this parameter is null. string

To configure the Telephony verification webhook for this component, expand for instructions.

  1. Open the Dialogflow CX console.
  2. Choose your Google Cloud project.
  3. Select your agent.
  4. Select the Manage tab.
  5. Click Webhooks.
  6. Select the prebuilt_components_authentication:telephony_verification webhook.
  7. Replace the URL in the Conversational Agents (Dialogflow CX) Webhook URL field with the endpoint for the service you want to integrate with. Select the proper Method in the dropdown.
  8. Review and update the Request body to form the proper request format for your webhook.
  9. Review and update the Response configuration to extract specific fields from your webhook's response. Do not modify the parameter names, as these are required by the component to access the returned field values.
  10. Review and update the Authentication settings as needed.
  11. Click Save.

Get credit card details

The prebuilt_components_account_services:get_credit_card_details webhook is used by the component to get information about the credit card(s) registered to a user.

API request parameters

The following parameters are provided by the component as inputs to the API request.

Parameter Name Description Input Format
$session.params.phone_number User's local phone number, without the country code, used to identify the user. string

API response parameters

The following parameters are pulled from the API response to be used by the component.

Parameter Name Description Output Format
credit_card_count The number of credit cards associated with the registered telephone number. integer
last_four_digit_of_credit_card_number If a user has a single credit card, the last four digits of the card number are returned. If a user has more than one card, the value of this parameter is null. string
email The email registered with the account. If there is no email registered with the account, the value of this parameter is null. string

To configure the Get credit card details webhook for this component, expand for instructions.

  1. Open the Dialogflow CX console.
  2. Choose your Google Cloud project.
  3. Select your agent.
  4. Select the Manage tab.
  5. Click Webhooks.
  6. Select the prebuilt_components_account_services:get_credit_card_details webhook.
  7. Replace the URL in the Conversational Agents (Dialogflow CX) Webhook URL field with the endpoint for the service you want to integrate with. Select the proper Method in the dropdown.
  8. Review and update the Request body to form the proper request format for your webhook.
  9. Review and update the Response configuration to extract specific fields from your webhook's response. Do not modify the parameter names, as these are required by the component to access the returned field values.
  10. Review and update the Authentication settings as needed.
  11. Click Save.

Send OTP

The prebuilt_components_authentication:send_otp webhook is used by the component to send a one-time password (OTP) to a registered channel selected by the end-user.

API request parameters

The following parameters are provided by the component as inputs to the API request.

Parameter Name Description Input Format
$session.params.phone_number User's local phone number, without the country code, used to identify the user. string
$flow.channel The channel the user has selected to receive the OTP on. Valid values are defined by the prebuilt_components_authentication_channel custom entity. By default email and mobile are supported. string

API response parameters

The following parameters are pulled from the API response to be used by the component.

Parameter Name Description Output Format
generated_otp The value of the OTP generated and sent to the user using the selected channel. string

To configure the Send OTP webhook for this component, expand for instructions.

  1. Open the Dialogflow CX console.
  2. Choose your Google Cloud project.
  3. Select your agent.
  4. Select the Manage tab.
  5. Click Webhooks.
  6. Select the prebuilt_components_authentication:send_otp webhook.
  7. Replace the URL in the Conversational Agents (Dialogflow CX) Webhook URL field with the endpoint for the service you want to integrate with. Select the proper Method in the dropdown.
  8. Review and update the Request body to form the proper request format for your webhook.
  9. Review and update the Response configuration to extract specific fields from your webhook's response. Do not modify the parameter names, as these are required by the component to access the returned field values.
  10. Review and update the Authentication settings as needed.
  11. Click Save.

Security answers

The prebuilt_components_authentication:security_answers webhook is used by the component to retrieve the end-user's security answers from their registered account.

API request parameters

The following parameters are provided by the component as inputs to the API request.

Parameter Name Description Input Format
$session.params.phone_number User's local phone number, without the country code, used to identify the user. string

API response parameters

The following parameters are pulled from the API response to be used by the component.

Parameter Name Description Output Format
security_last_trans_amount Indicates the full amount of the user's last transaction, with no currency symbol. For example, if the user's last transaction amount is $100.30 USD, the expected value of this field is "100.30". string
last_payment_mode The payment method used for the user's last transaction, with valid values defined by the prebuilt_components_authentication_payment_mode custom entity. By default these values include mobile, upi, online, debit, credit, and account. string
security_card_number The last four digits of the user's debit card number. string
user_dob The date of birth (DOB) of the user in YYYY-MM-DD format. string
cards_exp_date_all The expiration dates of all credit cards registered with the user in MMYYYY format. List (string)

To configure the Security answers webhook for this component, expand for instructions.

  1. Open the Dialogflow CX console.
  2. Choose your Google Cloud project.
  3. Select your agent.
  4. Select the Manage tab.
  5. Click Webhooks.
  6. Select the prebuilt_components_authentication:security_answers webhook.
  7. Replace the URL in the Conversational Agents (Dialogflow CX) Webhook URL field with the endpoint for the service you want to integrate with. Select the proper Method in the dropdown.
  8. Review and update the Request body to form the proper request format for your webhook.
  9. Review and update the Response configuration to extract specific fields from your webhook's response. Do not modify the parameter names, as these are required by the component to access the returned field values.
  10. Review and update the Authentication settings as needed.
  11. Click Save.

Two-factor validation

The prebuilt_components_authentication:2fa_validation webhook is used by the component to validate the security key provided by the end-user for two-factor authentication.

API request parameters

The following parameters are provided by the component as inputs to the API request.

Parameter Name Description Input Format
$session.params.phone_number User's local phone number, without the country code, used to identify the user. string
$flow.security_key The security key provided by the end-user, generated using a bank app or authenticator app. string

API response parameters

The following parameters are pulled from the API response to be used by the component.

Parameter Name Description Output Format
security_key_verified Indicates whether the end-user's provided security key is valid. true indicates that the provided security key is valid. false indicates that the provided security key is invalid. boolean

To configure the Two-factor validation webhook for this component, expand for instructions.

  1. Open the Dialogflow CX console.
  2. Choose your Google Cloud project.
  3. Select your agent.
  4. Select the Manage tab.
  5. Click Webhooks.
  6. Select the prebuilt_components_authentication:2fa_validation webhook.
  7. Replace the URL in the Conversational Agents (Dialogflow CX) Webhook URL field with the endpoint for the service you want to integrate with. Select the proper Method in the dropdown.
  8. Review and update the Request body to form the proper request format for your webhook.
  9. Review and update the Response configuration to extract specific fields from your webhook's response. Do not modify the parameter names, as these are required by the component to access the returned field values.
  10. Review and update the Authentication settings as needed.
  11. Click Save.

Complete

Your agent and its webhooks should now be set up and ready to test.