The authentication
[prebuilt component](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component)
collects information from the user to reach the required authentication level.
This component covers authentication requirements that are common, but not
exclusive, to the financial services (FSI) industry. It uses the
[Credit card expiration date collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/credit-card-expiration-date-collection),
[Date of birth collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/date-of-birth-collection),
and [Telephone number collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/telephone-number-collection)
prebuilt components to collect and validate user details.

## Authentication levels

Different prebuilt components require multiple levels of authentication, with
higher levels requiring more user information to authenticate.

The authentication component lets the user authenticate to Level 0 (ANI Match),
Level 1 (Basic), or Level 2 (Multi-factor) as described in the following table:

| Authentication Level | Requirements |
|---|---|
| Level 0: ANI Match | Authenticates the user by calling from or providing a phone number that corresponds to a registered account. The user can authenticate to Level 0 by using the [Greeting prebuilt component](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/greeting). |
| Level 1: Basic | Authenticates the user by verifying a one-time password (OTP) code sent to their email or phone number. If OTP verification fails, the user can provide answers to three out of four security questions 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're an account or card holder), last transaction amount, and last credit card bill payment method. |
| Level 2: Multi-factor | Additionally authenticates the user by verifying a security key generated by an external authenticator app or push notification. |

## Supported user types

The authentication component supports enrolled bank customers who are account
holders, card holders, or both. The component also supports authentication for
users who aren't enrolled bank customers but who have power of attorney for
accounts registered with the bank. The user can have one or more accounts or
cards registered with the bank.

## Authentication types

This component lets you configure whether the user should be authenticated as
an account holder, a card holder, or both. You can set these options by using
the `$session.params.account_auth_enabled` and
`$session.params.card_auth_enabled` [input parameters](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#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 is 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 is 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](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-levels). 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](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-levels). |

## Limitations

In addition to the
[common prebuilt component limitations](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component#limits),
this prebuilt component has the following limitations:

- OTPs are sent only to a mobile number or email address previously registered to the account. The component doesn't use OTP to authenticate customers calling from an alternate phone number that isn't registered with their account. When calling from an alternate phone number, security questions authenticate the user.
- This component doesn't encrypt data.

## Sample dialogs

The following sample dialogs demonstrate common scenarios that this prebuilt
component handles. The dialogs show behavior when telephony calls the
component, which triggers the Default Welcome Intent and the first agent
response at the start of the conversation.

### Level 1 authentication success: OTP

1. The component verifies that the user has been authenticated to Level 0.
2. The component sends an OTP to the channel of the user's choice.
3. The component asks the user to confirm the OTP.
4. The user provides a valid OTP to authenticate 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

1. The component confirms the user's Level 0 authentication by collecting and verifying the provided phone number.
2. The component asks for and validates the user's correct answers to three security questions, including the date of birth, the last four digits of the user's debit card number, and the last transaction amount.
3. The user successfully authenticates 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. |
|   | *The agent collects the user's telephone number using [Telephone number collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/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. |
|   | *The agent collects the user's date of birth using [Date of birth collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/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

1. The user has previously been authenticated to Level 1 authentication.
2. The user generates a security key using their bank app or authenticator app.
3. The user provides the security key to the component to authenticate 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

1. The user declines to provide information required to authenticate.
2. 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. |
|   | *The agent collects the user's date of birth using [Date of birth collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/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 configure certain behaviors of the component. One or more
conditions within the flow use the parameters to determine how the component
behaves. The user must set flow-scoped parameters on the start page of the
component as described in the following table. The caller can set
session-scoped parameters using 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](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-levels) of the user. | integer |
| $session.params.auth_level_req | Defines the [authentication level](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-levels) the 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](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-types). | 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](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-types). | boolean |
| $session.params.phone_number | (optional) The user's local phone number, without the country code. If this parameter is not provided, the component will collect the phone number from the 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 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](https://dialogflow.cloud.google.com/cx/projects).
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 remain active after the user
exits the component. These parameters contain important information that the
component collects.

This prebuilt component provides values for the following output parameters:

| Parameter Name | Description | Output Format |
|---|---|---|
| auth_level | Indicates the current [authentication level](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-levels) of the user. | integer |
| phone_number | The local phone number provided by the user, without the country code. | string |
| transfer_reason | This parameter indicates the reason the flow exited, if it was not successful. The returned value is one of: `agent`: the user requested a human agent at some point during the conversation. `denial_of_information`: the 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](https://docs.cloud.google.com/dialogflow/cx/docs/concept/handler#event-built-in). `max_no_match`: the conversation reached the maximum number of retries for no-match events. See [no-match built-in events](https://docs.cloud.google.com/dialogflow/cx/docs/concept/handler#event-built-in). `webhook_error`: a webhook error occurred. See [webhook.error built-in event](https://docs.cloud.google.com/dialogflow/cx/docs/concept/handler#event-built-in). `webhook_not_found`: a webhook URL was unreachable. See [webhook.error.not-found built-in event](https://docs.cloud.google.com/dialogflow/cx/docs/concept/handler#event-built-in). | string |

## Basic setup

To set up this prebuilt component:

1. [Import the prebuilt component](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component#import).
2. Configure the provided [flexible webhooks](https://docs.cloud.google.com/dialogflow/cx/docs/concept/webhook#flexible) with settings describing your external services, see [Webhook setup](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#webhook-setup).

## Webhook setup

To use this component, the user must configure the included
[flexible webhooks](https://docs.cloud.google.com/dialogflow/cx/docs/concept/webhook#flexible) to retrieve
needed information from their 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 component provides the following parameters as inputs to the API request:

| Parameter Name | Description | Input Format |
|---|---|---|
| $session.params.phone_number | The user's local phone number, without the country code. | string |

#### API response parameters

The component pulls the following parameters from the API response:

| 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](https://dialogflow.cloud.google.com/cx/projects).
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 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 component uses the
`prebuilt_components_account_services:get_credit_card_details` webhook to
retrieve information about the credit cards registered to a user.

#### API request parameters

The component provides the following parameters as inputs to the API request:

| Parameter Name | Description | Input Format |
|---|---|---|
| $session.params.phone_number | The user's local phone number, without the country code. | string |

#### API response parameters

The component pulls the following parameters from the API response:

| 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](https://dialogflow.cloud.google.com/cx/projects).
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 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 sends a one-time
password (OTP) to a registered channel that you select.

#### API request parameters

The component provides the following parameters as inputs to the API request:

| Parameter Name | Description | Input Format |
|---|---|---|
| $session.params.phone_number | The user's local phone number, without the country code. | 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 component pulls the following parameters from the API response:

| 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](https://dialogflow.cloud.google.com/cx/projects).
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 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 retrieves
the user's security answers from their registered account.

#### API request parameters

The component provides the following parameters as inputs to the API request:

| Parameter Name | Description | Input Format |
|---|---|---|
| $session.params.phone_number | The user's local phone number, without the country code. | string |

#### API response parameters

The component pulls the following parameters from the API response:

| 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](https://dialogflow.cloud.google.com/cx/projects).
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 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 lets the
component validate the security key provided by the user for two-factor
authentication.

#### API request parameters

The component provides the following parameters as inputs to the API request:

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

#### API response parameters

The component pulls the following parameters from the API response:

| Parameter Name | Description | Output Format |
|---|---|---|
| security_key_verified | Indicates whether the 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](https://dialogflow.cloud.google.com/cx/projects).
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 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

The prebuilt component and its webhooks are now set up and ready to test.