OTPBySMSValve

Valve for delivering one-time passwords by SMS, using PhenixID Message Gateway .

Properties

Name Description Default value Mandatory Supports property expansion
generated_otp_name Item property containing the generated otp. generated_otp No No
recipient_param_name Property containing the recipient mobile number. mobile No Yes
userid_param_name Property containing the username. User-Name No Yes
wash_recipient_number If the mobile number should be washed (i.e. removal of whitespaces, - and other non-number characters). true No No
use_flash If the SMS message should be sent as flash. true No No
recipient_prefix Prepends the recipient number with a country prefix if it starts with '0'. (example: +46) No No
force_prefix Always prepends the recipient number with the configured prefix. No No
remove_leading_plus If the leading + character should be removed from the mobile number. false No No
gatewayURL URL(s) to PhenixID Message Gateway(s) No No
message_gateway_settings PhenixID Message Gateway Settings. Yes No
gw_username PhenixID Message Gateway username to override PhenixID Message Gateway Settings. No No
gw_password PhenixID Message Gateway password to override PhenixID Message Gateway Settings. No No
message_key Locale key for the sms message. Found in lang/*/strings.xml, in the pipes module. valves.otp.sms.message No No
message Static, non localizeable message. Overrides message_key parameter. No No
dynamic_values Dynamic template mapping values. Separated by pipe (|) Replaces key with value in the message sent to user.
Syntax: $$USERNAME={{item.givenName}}|$$SOME_OTHER_KEY={{item.somevalue}}
See example below.		 No Yes

Example Configuration 

{
        "name": "OTPBySMSValve",
        "config": { 
              "recipient_param_name":"{{request.mobile}}",
              "userid_param_name":"{{request.username}}",
              "generated_otp_name" : "generated_otp",
              "wash_recipient_number" : "true",
              "use_flash" : "false",
              "recipient_prefix" : "+46",
              "force_prefix" : "true",
              "message_gateway_settings" : "ce4d2wer-css0-42ec-9800-129a6212",
              "message" : "Hello $$USERNAME, your OTP is: $$OTP",
              "dynamic_values" : "$$USERNAME={{item.givenName}}"
        }
}

 In the example above the value for attribute mobile has been picked up earlier in the flow.

The value for userid_param_name has been picked up from the request. Most common values are {{request.User-Name}} for RADIUS and {{request.username}} for HTTP.

Requirements

Item set must have at least one entry.

SMS request rate limiter

The rate at which SMS messages can be sent to any single recipient number is limited by the system, based on a moving average of the delay between consecutive requests. This functionality is characterised by four parameters, described below. 

Example, based on the default settings: a user that requests five SMS OTP:s, to the same number, within a period of 2.5 minutes will be quarantined for a period of 10 minutes, after which the limiter is reset and the user can start requesting SMS OTP:s again. 

The parameters are global and specified on the phenix-pipes module configuration, not on the valve configuration. Changes will affect all SMS valves.

Name
 Description
 Default value
request_interval_mean
 A lower bound for the moving average delay between consecutive requests, in seconds.
 30
request_lookback
 The number of recent requests that are used to calculate the moving average.
 5
request_quarantine_period
 If the average delay between requests in the lookback period drops below the lower bound, the recipient number will be quarantined for the period specified by this parameter, in seconds. After the quarantine period expires, the average delay calculation is reset.
 600
request_limiter_disabled
 Disables the limiter function.
 false