Configuring validity for the key
For security purposes, you can configure a validity period for the generated key while validating the OTP. This prevents a user session from remaining active indefinitely even after they log out.
Note
To enable these configurations, you need to raise a ticket. The turn around time is 5 days.
Configuration | Description | Default value |
---|---|---|
CONF_ENABLE_EXPIRY_BASED_KEY | Set the value to True to enable the configuration. | False (Disabled) |
CONF_KEY_EXPIRY_IN_MINUTES | Defines the expiry time. | 60 minutes |
CONF_KEY_EXPIRY_MFA_IN_MINUTES | Defines the expiry time for the key generated for the MFA token | 60 minutes |
Defining maximum OTP retry attempts
You can define the below configurations and set the maximum OTP/password retry attempts. If the user attempts more than the defined number, the account gets locked for that particular session. To restrict the user from starting a new session and reattempting the OTP or password, it is recommended to activate the account locking feature.
Configuration | Description | Default value |
---|---|---|
CONF_MAX_OTP_RETRY_COUNT | Defines the maximum number of allowed attempts to enter the primary OTP. | - |
CONF_MAX_PASSWORD_RETRY_COUNT | Defines the maximum allowed attempts to enter the primary password. | - |
CONF_MFA_MAX_OTP_RETRY_COUNT | Defines the maximum allowed attempts to enter the MFA OTP. | - |
CONF_MFA_MAX_PASSWORD_RETRY_COUNT | Defines the maximum allowed attempts to enter the MFA password | - |
Account locking feature
You can configure the account-locking feature to lock a user account after several defined unsuccessful attempts to enter the correct OTP. For example, if the OTP maximum attempt is defined as five and the user enters incorrect OTPs more than five times, you can configure the account locking in such a way that the account gets locked for a defined time. The account unlocks after the specified number.
Configuration | Description | Default value |
---|---|---|
CONF_ENABLE_ACCOUNT_LOCKING | Enables the account locking feature for the OTP and password. | False |
CONF_LOCK_PERIOD_IN_MINUTES | Defines the duration of account locking after entering the OTP/password incorrectly for the specified number of times. The maximum value allowed is 43,200 minutes. | 30 minutes |
CONF_ENABLE_ACCOUNT_LOCKING_MFA | Enables the account locking feature for the MFA OTP/password. | False |
CONF_MFA_LOCK_PERIOD_IN_MINUTES | Defines the duration of account locking after entering the MFA OTP/password incorrectly for the specified number of times. The maximum value allowed is 43,200 minutes. | 30 minutes |
CONF_INCORRECT_ATTEMPT_INTERVAL | Defines the time interval after which any subsequent attempt is considered a new one, resetting the incorrect OTP/password counter. For more information, refer to the detailed explanation below. Note: This is applicable for both primary/MFA OTP and primary/MFA passwords. | 30 minutes |
Configuring incorrect attempt time interval
Attention
Make sure that you define a time interval so that the user does not misuse the OTP/password attempts. For example, if you define one minute, the user can wait for one minute after an incorrect OTP/password attempt and start fresh OTP/password attempts
This value defines the time interval after which, any subsequent attempt is considered a new one, resetting the incorrect OTP/password counter. The OTP/password attempts within this time interval are counted together.
Example
Consider that the value is set as five minutes.
- User A attempts to log in but enters the wrong OTP.
- The system records this as the first incorrect attempt and starts a 5-minute countdown timer.
Within 5 minutes, User A attempts to log in again but enters the wrong OTP once more. - Since the second attempt is made within the defined interval of five minutes, the system continues to consider the attempts made within this 5-minute window as part of the same attempt count.
- If User A makes another incorrect attempt after the 5-minute interval has elapsed, it will be considered as the first incorrect attempt again, and the process repeat.
Integrating WhatsApp and Zalo for OTP communication
You can enable and configure the below configs to integrate WhatsApp and Zalo to send OTPs.
Configuration | Description | Default Value |
---|---|---|
CONF_MOBILE_SUB_CHANNEL | Channel to send the primary OTP to the user. Values: WHATSAPP or ZALO. | - |
CONF_MOBILE_SUB_CHANNEL_PROPERTIES | Properties for each subchannel (WHATSAPP and ZALO) in JSON format. The message will be sent in this format. | {"WHATSAPP": { "template": "OTP generated for whatsapp is {otp}" }, "ZALO": { "template": "OTP generated for zalo is {otp}" }} |
CONF_MFA_MOBILE_SUB_CHANNEL | Channel to send MFA OTP to the user. Values: WHATSAPP or ZALO. | - |
CONF_MFA_MOBILE_SUB_CHANNEL_PROPERTIES | Properties for each subchannel (WHATSAPP and ZALO) in JSON format. The message will be sent in this format. | {"WHATSAPP": { "template": "OTP generated for whatsapp is {otp}" },"ZALO": { "template": "OTP generated for zalo is {otp}" }} |
CONF_FALLBACK_CHANNELS | Specifies the fallback communication channel to send the OTP. Supported values: any channel except the defined primary subchannel. See Fallback channel for more details. | - |
CONF_FALLBACK_CHANNELS_PROPERTIES | Defines the properties for each fallback channel (WHATSAPP, ZALO, SMS) in JSON format. | {"WHATSAPP": { "template": "OTP generated for whatsapp is {otp}" },"ZALO": { "template": "OTP generated for zalo is {otp}" },"SMS": { "template": "OTP generated for sms is {otp}" }} |
Fallback channel
A fallback channel is used to skip the defined primary subchannel and send the OTP to the communication channel defined in this config. If you have defined a fallback channel and if you use fallbackChannel={comm channel}
as a query parameter in the OTP generate API URL, the system ignores the defined sub-channel and sends the OTP to the channel defined in the fallback channel configuration. For example,
if CONF_MOBILE_SUB_CHANNEL = WHATSAPP,
CONF_FALLBACK_CHANNELS = SMS, and
OPT generate URL = https\://{host}/auth/v1/web/otp/generate?fallbackChannel=SMS
the system always sends the OTP using SMS as the communication channel.
This feature can be used to send OTP to a different channel if the sub-channel is not reachable.
Error codes
Error code | Solution |
---|---|
1601 Fallback Channel needs identifier mobile | Ensure 'mobile' is passed in the body if fallback channel is set as mobile. |
1602 Fallback Channel needs identifier email | Ensure 'email' is passed in the body if fallback channel is set, instead of query params. |
1603 Channel is not configured properly, please check and try again | Verify subchannel/fallback channel configuration is valid. |