MTAN/SMS Settings
Settings related to mTAN/SMS (authentication, self-registration, administration, etc.). These settings are used by various components in Airlock IAM.
Loginapp flows typically have step-specific mTAN settings and only refer to these global settings if plugins with "(based on mTAN Settings)" in the name are used.
mtanHandler) An mTAN handler retrieves, creates and updates MTAN number tokens.
- in the mTAN/SMS Authenticator
- in the Adminapp
- in Service Container tasks
- in flow steps if the settings "based on mTAN Settings" are used
- for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
smsGateway) The SMS gateway used to send messages.
This property is used for the following:
- in the mTAN/SMS Authenticator
- in the Adminapp
- in flow steps if the settings "based on mTAN Settings" are used
- for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
originatorName) The originator that is displayed for the SMS messages (instead of the phone number).
There may be restrictions on the originator imposed by the SMS gateway service and by local law.
The format of the originator must be one of:
- Numeric characters only, optionally prefixed with a plus sign '+', at most 16 characters
- Alphanumeric characters, at most 11 characters
This property is used for the following:
- in the mTAN/SMS Authenticator
- in the Adminapp
- in flow steps if the settings "based on mTAN Settings" are used
- for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
useFlashMessages) If enabled, SMS messages are sent as 'flash SMS' by default. A flash message is shown directly on the mobile phone display.
Note: If the per-user setting is set, it takes precedence as long as a value is set for a user. If it is empty or not set, this default value is used.
Note: This has to be supported by the SMS gateway. Some recipients might have not be able to receive flash messages.
This property is used for the following:
- in the mTAN/SMS Authenticator
- in the Adminapp
- in flow steps if the settings "based on mTAN Settings" are used
- for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
defaultCountryCode) Default country code to be used if a phone number does not contain a country code.
This property is used for the following:
- in the mTAN/SMS Authenticator
- in the Adminapp
- in flow steps if the settings "based on mTAN Settings" are used
- for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
otpGenerator) The string generator plugin to generate the OTP token.
This property is used for the following:
- in the mTAN/SMS Authenticator
- in the Adminapp
- in flow steps if the settings "based on mTAN Settings" are used
- for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
visiblePhoneNumberDigits) Defines the number of phone number digits that are displayed to the user or the administrator.
If the value is zero, all digits are masked, if it is large enough (e.g. 100), all digits are visible. Example: if set to 3, logged number looks like ********965.
This property is used for the following:
- in the mTAN/SMS Authenticator
- in the Adminapp
- in flow steps if the settings "based on mTAN Settings" are used
- for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
messageTemplateKey) The message template can be defined in the string resource files, to enable language-specific messages to be sent to the user.
This property is only used in the mTAN/SMS Authenticator and for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
ignoreTokenCase) If enabled the case of characters is ignored when checking OTP tokens.
This property is used for the following:
- in the mTAN/SMS Authenticator
- in flow steps if the settings "based on mTAN Settings" are used
- for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
maxTokenRetransmissions) Maximum number of times an OTP token may be requested to be retransmitted during one authentication process. The authentication is aborted if this limit is exceeded. Token retransmissions are disabled if this value is 0. Restricting this value to a small number prevents the abusive use of SMS delivery.
This property is only used in the mTAN/SMS Authenticator and the mTAN Authentication Step if the settings "based on mTAN Settings" are used.
retransmitSameToken) If token retransmissions are enabled this sets whether the OTP token should be retransmitted or whether a new OTP should be generated for each retransmission.Setting this property totrue is less secure but helps avoiding erroneous user input when the initial OTP is received before retransmission.
This property is only used in the mTAN/SMS Authenticator and the mTAN Authentication Step if the settings "based on mTAN Settings" are used.
otpValidity) Determines how long the OTP is valid (in seconds).
This property is only used in the mTAN/SMS Authenticator and for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
maxTokenRetries) The number of times a user may retry after a wrong token is entered before the authentication process is aborted.
If set to zero (the default), only one attempt is possible for each token. This is more secure but may increase costs (if sending a token is costly) and negatively affects usability. Setting this value to n means that the user has n+1 tries in total.
This property is only used in the mTAN/SMS Authenticator and the mTAN Authentication Step if the settings "based on mTAN Settings" are used.
allowPhoneNumberChange) If enabled, the user may change an already registered mobile phone number by starting the registration process for mobile phone numbers. If disabled (the default), changing an already registered number is not possible.
This property is only used for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
phoneNumberValidationRegex) If enabled the phone number entered by the user is matched against this regular expression. This regex match takes place after (optional) normalization. Using with normalization allows to check for simpler rules, because it means that the number is already transformed into the international form without spaces, e.g. "+41761234567".
E.g. to only allow Swiss numbers, set the default Country Code to 41, and validate the resulting number with \+41(\d){9,9}
This property is only used for the /protected/my/tokens/mtan/ REST endpoints if the settings "based on mTAN Settings" are used.
mayBeSelectedAsAuthMethod) mayBeSelectedAsNextAuthMethod) adminMayEditPhoneNumber) notifyNewNumber) notificationSmsTemplate) Message template for the notification SMS. Defining this property enables the "Send Test SMS" button on the mTAN detail view on the user page. If the property "Notify New Number" is enabled, it is also used for the SMS that is sent to a new or changed phone number.
If the template contains the "$TOKEN$"-variable, it is replaced by a randomly generated OTP that can be verified by the administrator.
type: MtanSettings
id: MtanSettings-xxxxxx
displayName:
comment:
properties:
adminMayEditPhoneNumber: false
allowPhoneNumberChange: false
defaultCountryCode: 41
ignoreTokenCase: false
maxTokenRetransmissions: 0
maxTokenRetries: 0
mayBeSelectedAsAuthMethod: true
mayBeSelectedAsNextAuthMethod: true
messageTemplateKey:
mtanHandler:
notificationSmsTemplate:
notifyNewNumber: false
originatorName:
otpGenerator:
otpValidity: 300
phoneNumberValidationRegex:
retransmitSameToken: false
smsGateway:
useFlashMessages: false
visiblePhoneNumberDigits: 100