OTP Validation

Use this valve to validate a generated one-time password suite¹. On success, user_authenticated is set to "true" on the item. On failure, a PipeException is thrown — unless otp_retries is configured, in which case the valve soft-fails and lets the calling flow handle the error.

Retry behavior

When otp_retries > 0, a failed validation resolves instead of throwing. The valve writes the current failure count and the configured limit to the item. The calling flow is responsible for persisting otp_fails from the item to the session between attempts — the valve reads the counter from the session to perform its pre-check.

Pre-check: at the start of each call, the valve reads otp_fails from the session. If the value is greater than or equal to otp_retries, the request is blocked without validating the OTP. By default the pre-check also soft-fails; set otp_strict: true to make it throw instead.

Configuration

Note

Valve name: ValidateOtp | OtpValidation

Properties

Name	Description	Default value	Mandatory	Expanded
username_parameter	Parameter containing the username.	N/A
otp_parameter	Parameter containing the entered OTP.	N/A
src_parameter	Parameter containing the previously generated OTP.	"${session.generated_otp}"
otp_retries	Maximum number of accepted failures before the pre-check blocks the request. When 0, any failed OTP throws immediately.	0
otp_strict	When true, the pre-check throws a PipeException instead of soft-failing when the retry counter is exhausted.	false

Output properties

Name	Value	When
user_authenticated	"true"	OTP validated successfully.
otp_failed	"true"	Validation failed and otp_retries > 0 (soft-fail or pre-check).
otp_fails	Current failure count as a string.	Soft-fail or pre-check. The calling flow must persist this value to the session.
otp_accepted_fails	Value of otp_retries as a string.	Soft-fail or pre-check.

Example

{
    "name": "ValidateOtp",
    "enabled": true,
    "config": {
        "username_parameter": "${request.User-Name}",
        "otp_parameter": "${request.User-Password}",
        "src_parameter": "${session.generated_otp}",
        "otp_retries": 3,
        "otp_strict": true
    }
}

Footnotes

1. A suite is the "full" one-time password value containing otp_value,creation_time,valid_time. ↩