Authentication configurations

Enable MFA password flow

Below are the configurations for the password flow in MFA.

ConfigurationDescriptionDefault valueApplicability
(MFA/Primary flow - First factor authentication)
IS_MFA_PASSWORD_ENABLEDDetermines if the password flow in MFA is enabledFalseMFA
MFA_PASSWORD_REGEXSystem verifies the user-entered password against the password in this config.MFA

Note: The above two configurations are independent and must be enabled separately.

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 turnaround time is 5 days.

ConfigurationDescriptionDefault valueApplicability
(MFA/Primary flow - First factor authentication)
CONF_ENABLE_EXPIRY_BASED_KEYSet the value to True to enable the configuration. False (Disabled)Both
CONF_KEY_EXPIRY_IN_MINUTESDefines the expiry time.60 minutesPrimary
CONF_KEY_EXPIRY_MFA_IN_MINUTESDefines the expiry time for the key generated for the MFA token60 minutesMFA

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.

ConfigurationDescriptionDefault valueApplicability
(MFA/Primary flow - First factor authentication)
CONF_MAX_OTP_RETRY_COUNTDefines the maximum number of allowed attempts to enter the primary OTP.5Primary
CONF_MAX_PASSWORD_RETRY_COUNTDefines the maximum allowed attempts to enter the primary password.5Primary
CONF_MFA_MAX_OTP_RETRY_COUNTDefines the maximum allowed attempts to enter the MFA OTP.5MFA
CONF_MFA_MAX_PASSWORD_RETRY_COUNTDefines the maximum allowed attempts to enter the MFA password5MFA

Enable API encryption

You can enable encryption for particular APIs using this configuration. Enabling the configuration safeguards the auth-engine from being exploited by triggering OTPs multiple times. If the encryption logic is enabled for a brand, the APIs to generate OTP have to go through the encryption flow.

ConfigurationDescriptionDefault valueApplicability
(MFA/Primary flow - First factor authentication)
CONF_ENABLE_ENCRYPTIONTo enable the encryption. False (Disabled)Both
CONF_ENCRYPTION_PUBLIC_KEYTo store the org's public key. The keys are encoded in Base64 format and are constant and do not change.Both
CONF_ENCRYPTION_PRIVATE_KEYTo store the org's private key. The keys are encoded in Base64 format and are constant and do not change.Both
CONF_ENCRYPTION_VALID_IN_SECONDSTo define the time window during which it considers requests as valid.120 secondsBoth
CONF_ENCRYPTION_ENDPOINTSTo define the API endpoints for which the payload needs to be encrypted. You can encrypt the payload of the APIs otp/generate (OTP) and mfa/otp/generate (MFA_OTP) API""Both

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.

ConfigurationDescriptionDefault valueApplicability
(MFA/Primary flow - First factor authentication)
CONF_ENABLE_ACCOUNT_LOCKINGEnables the account locking feature for the OTP and password.FalsePrimary
CONF_LOCK_PERIOD_IN_MINUTESDefines 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 minutesPrimary
CONF_ENABLE_ACCOUNT_LOCKING_MFAEnables the account locking feature for the MFA OTP/password.FalseMFA
CONF_MFA_LOCK_PERIOD_IN_MINUTESDefines 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 minutesMFA
CONF_INCORRECT_ATTEMPT_INTERVALDefines 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 minutesBoth

General configurations

Below are some general configurations related to the OTP and token generation in MFA and primary flows.

ConfigurationDescriptionDefault valueApplicability
(MFA/Primary flow - First factor authentication)
CONF_TOKEN_SESSION_EXPIRY_MINUTESDefines the expiry time of the session created while generating the token in the primary flow15 minutesPrimary
CONF_MFA_TOKEN_SESSION_EXPIRY_MINUTESDefines the expiry time of the session created while generating the MFA token in the MFA flow15 minutesMFA
CONF_MFA_TOKEN_EXPIRY_IN_MINUTESDefines the validity of the token created in MFA flow.15 minutesMFA
CONF_MFA_SESSION_EXPIRY_MINUTESDefines the validity of the MFA session.15 minutesMFA
CONF_OTP_LENGTHDefines the length of the One-time password6Both
CONF_REGENERATE_TOKENIf enabled, a key is generated after validating the OTP/password. This key is used to regenerate the token from the primary flow.TruePrimary
CONF_REGENERATE_MFA_TOKENIf enabled, a key is generated after validating the OTP/password. This key is used to regenerate the token from the MFA flow.TrueMFA
MFA_ROLEDefines the user role for both MFA and primary flows.
If the user is not enrolled for MFA, the role is set to USER.
If enrolled for MFA, the role is set to MFA_PENDING.
After the MFA process, the role is set to USER.
DEFAULT_MFA_ROLEBoth
CONF_FORCED_MFADefines if all users need to be forced into the MFA role.
If set to True, all the users are set to MFA_PENDING and moved to the USER role after the MFA process.
FalseBoth
CONF_EXTERNAL_ID_LOGIN_ENABLEDIf enabled, a user is fetched from the Intouch portal if not in the auth-engine.FalsePrimary
CONF_OTP_SEND_FOR_EXTERNAL_IDDefines where the OTP is to be sent. Possible values: mobile or email.MobileBoth
CONFIG_REJECT_NON_CF_CALLSEnforces validation for CloudFront calls during OTP generate requests.
If enabled, the system expects a specific header during the OTP generation call. If the header is missing, the request to generate OTP is rejected.
FalseBoth
CONF_SKIP_OTP_VALIDATEIf enabled, disables the requirement for OTP validation during the MFA password set-up.FalseMFA
CONF_SKIP_OTP_VALIDATE_RESETIf enabled, disables the requirement for OTP validation during the MFA password reset.FalseMFA
CONF_AUTO_FILL_2ND_FACTOR_IDENTIFIERIf enabled, the identifier type and value are automatically populated for each API of the MFA flow. This occurs for the particular session for which the token is generated from the primary flow.FalseMFA

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.

ConfigurationDescriptionDefault ValueApplicability
(MFA/Primary flow - First factor authentication)
CONF_MOBILE_SUB_CHANNELChannel to send the primary OTP to the user. Values: WHATSAPP or ZALO.-Primary
CONF_MOBILE_SUB_CHANNEL_PROPERTIESProperties 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}" }}
Primary
CONF_MFA_MOBILE_SUB_CHANNELChannel to send MFA OTP to the user. Values: WHATSAPP or ZALO.-MFA
CONF_MFA_MOBILE_SUB_CHANNEL_PROPERTIESProperties 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}" }}MFA
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.-Both
CONF_FALLBACK_CHANNELS_PROPERTIESDefines 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}" }}Both

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 codeSolution
1601 Fallback Channel needs identifier mobileEnsure 'mobile' is passed in the body if fallback channel is set as mobile.
1602 Fallback Channel needs identifier emailEnsure '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 againVerify subchannel/fallback channel configuration is valid.