Multi-Factor Authentication Realm Settings Endpoint

phoneSetting

Settings for phone MFA methods

N / A

field1 - field4

Type of MFA method for designated phone field

phoneSmsSelected

Default radio button selected on client-side MFA methods page

If " field1" - "field4": "VoiceAndSmsText"

isVisible

Display both SMS and voice options even if both are not available

defaultCountryCode

Add country code that appends to all phone numbers in directory that do not include country code

any

mask

Regex mask of phone numbers that display on client-side MFA methods page

any

Phone numbers are automatically masked as ***-***-1234

phoneBlocking

Settings for phone number / type / carrier blocking

N / A

blockedSources

List of types of phones blocked from accessing realm

Any of the following:

blockRecentlyChangedCarrier

Block phone numbers that have recently changed carriers to avoid ported phone login attempts

allowApproveDeleteRecentlyChangedCarrier

Enable end-users to approve or delete carrier information when change is detected

If " blockRecentlyChangedCarrier": true

carrierStorageField

SecureAuth IdP profile property mapped to directory attribute that contains carrier information

If " blockRecentlyChangedCarrier": true

enableBlockAllowList

Create a list of carriers and / or countries that are denied or only allowed access to realm

listAction

Whether list of carriers and / or countries is allowed access or denied access to realm

If "enableBlockAllowList": true

phoneCarriers

List of carriers blocked or allowed access to realm, based on listAction value

see parameters for format requirements

Use the following endpoint to retrieve a list of available carrier country, codes, and names to block or allow:

GET https://<SecureAuth IdP Domain>/api/v1/realms/<realm ID>/phonecarriers

country

Country origin of carrier

see note

code

Carrier code

see note

name

Carrier name

see note

emailSetting

Settings for email MFA methods

N / A

field1 - field4

Type of MFA method for designated email field

knowledgeBasedSetting

Settings for knowledge based questions and answers MFA method

N / A

enableQuestions

Enable KBQ / KBA MFA method

format

Format and storage type of questions and answers in directory

questionCount

Number of questions asked during authentication process

doConversion

Convert KBQs to certificate-based encryption from Base64 encoding

helpDeskSettings

Settings for help desk MFA method

N / A

helpDesk1

Settings for help desk option 1 MFA method

N / A

helpDesk2

Settings for help desk option 2 MFA method

N / A

enabled

Enable selected MFA method

For help desk, PIN, and OATH Passcode MFA method configurations

phone

Phone number for help desk

any

email

Email address for help desk

any

pinSetting

Settings for personal identifying number (PIN) MFA method

N / A

openPin

Display PIN in directory as plain text

oneTimeUse

One-time use PIN that is immediately cleared from directory once used for authentication

Commonly used for first time user enrollment

showWhenEmpty

Display one-time use PIN option on client-side login page even when value is empty

oath

Settings for OATH passcode MFA method

N / A

passcodeLength

Number of digits composing OATH passcode

passcodeChangeInterval

Number of seconds during which passcode is valid

number, defaulted to 60

passcodeOffset

Number of minutes during which passcode is offset to make up for time differences between devices

number, defaulted to 5

cacheLockoutDuration

Number of minutes during which SecureAuth IdP disables use of OATH passcodes for locked account

number, defaulted to 10

pushNotification

Settings for push MFA methods

N / A

requestType

Type of push method to use

loginRequestTimeout

Number of minutes during which login request is valid

1 - 5 minutes

acceptMethod

Type of login request response

companyName

Name of company that displays on login request

any

applicationName

Name of application that displays on login request

any

maxDeviceCount

Number of push tokens allowed per user account at single time

number, defaulted to -1

-1: no maximum amount

exceedingMaxCountAction

Action to take when exceeding max token amount

If maxDeviceCount sets limit

replaceOrderBy

Method to replace existing tokens with new ones when exceeding max amount

If maxDeviceCount sets limit and " exceedingMaxCountAction": "AllowToReplace"

yubiKeySetting

Settings for YubiKey MFA method

N / A

enableYubiKeyAuthentication

Enable YubiKey as an MFA method

validateYubiKey

Validate YubiKey string via YubiCloud

storageLocation

SecureAuth IdP profile property mapped to directory attribute that contains YubiKey provisioning information

multiFactorSetting

Settings for MFA workflow

N / A

inlineInitializeMissingPhone

Allow end-users to provide phone number information is phone MFA methods are enabled and directory has no phone data

inlineInitializeMissingEmail

Allow end-users to provide email information is email MFA methods are enabled and directory has no email data

inlineInitializeMissingKbAnswers

Allow end-users to provide KBA information is KBQ MFA methods are enabled and directory has no KBA data

inlineInitializeMissingPin

Allow end-users to provide PIN information is PIN MFA method is enabled and directory has no PIN data

enableAutoSubmitWhenAvailable

Automatically submit MFA selection when only one MFA method is available

otpLength

Number of digits comprising one-time passcode

enableThrottling

Enable MFA method throttling

throttleMaxFailedAttempts

Number of MFA entries allowed within throttleInterval period before throttleAction occurs

number, defaulted to 5

throttleInterval

Amount of time during which throttleMaxFailedAttempts is limited

number, defaulted to 30

throttleTimeUnit

Unit of time for throttleInterval

throttleAction

Action to take when throttleMaxFailed Attempts is reached during throttleInterval

throttleStorageLocation

SecureAuth IdP profile property mapped to directory attribute that contains throttleMaxFailedAttempts count

Session: Browser session, no directory storage

otpValidateThrottleCount

Number of MFA entry validations allowed within otpValidateThrottleInterval period before throttleAction occurs

number

otpValidateThrottleInterval

Number of minutes during which otpValidateThrottleCount is limited

number

registrationMethodOrder

Order of MFA methods displayed on client-side MFA methods page

Create list of enabled methods:

See parameters for formatting

** For Symantec VIP - must be enabled and configured in UI, but order can be set via API

{
        "phoneSetting": {
                "field1": "VoiceAndSmsText",
                "field2": "LoginRequest",
                "field3": "Disabled",
                "field4": "Disabled",
                "phoneSmsSelected": "Voice",
                "isVisible": true,
                "defaultCountryCode": 1,
                "mask": ""
        },
        "phoneBlocking": {
                "blockedSources": [
                        "landline",
                        "virtual",
                        "landline_tollfree",
                        "pager",
                        "unknown"
                ],
                "blockRecentlyChangedCarrier": false,
                "allowApproveDeleteRecentlyChangedCarrier": false,
                "carrierStorageField": "AuxID2",
                "enableBlockAllowList": true,
                "listAction": "Block",
                "phoneCarriers": [
                        {
                                "Country": "United States",
                                "Code": "311490",
                                "Name": "SPRINT Spectrum L.P."
                        },
                        {
                                "Country": "United States",
                                "Code": "310271",
                                "Name": "AT&T Mobility"
                        },
                        {
                                "Country": "Mexico",
                                "Code": "334070",
                                "Name": "AT&T"
                        },
                        {
                                "Country": "United States",
                                "Code": "310200",
                                "Name": "T-mobile USA Inc."
                        },
                        {
                                "Country": "Austria",
                                "Code": "23203",
                                "Name": "T-Mobile Austria GmbH"
                        },
                        {
                                "Country": "United States",
                                "Code": "310910",
                                "Name": "Verizon Wireless"
                        }
                ]
        },
        "emailSetting": {
                "field1": "True",
                "field2": "TrueHtmlLink",
                "field3": "false",
                "field4": "false"
        },
        "knowledgeBasedSetting": {
                "enableQuestions": true,
                "format": "Base64",
                "questionCount": 2,
                "doConversion": false
        },
        "helpDeskSettings": {
                "helpDesk1": {
                        "enabled": true,
                        "phone": "555-555-1212",
                        "email": "YourSupport@Company.com"
                },
                "helpDesk2": {
                        "enabled": true,
                        "phone": "222-333-4444",
                        "email": "support@company.com"
                }
        },
        "pinSetting": {
                "enabled": true,
                "openPin": false,
                "oneTimeUse": false,
                "showWhenEmpty": false
        },
        "oath": {
                "enabled": true,
                "passcodeLength": 6,
                "passcodeChangeInterval": 60,
                "passcodeOffset": 5,
                "cacheLockoutDuration": 10
        },
        "pushNotification": {
                "requestType": “PasscodeAndAcceptDeny",
                "loginRequestTimeout": 1,
                "acceptMethod": "DisplaySymbol",
                "companyName": "ACME",
                "applicationName": "Salesforce",
                "maxDeviceCount": -1,
                "exceedingMaxCountAction": "AllowToReplace",
                "replaceOrderBy": "CreatedTime"
        },
        "yubiKeySetting": {
                "enableYubiKeyAuthentication": true,
                "validateYubiKey": true,
                "storageLocation": "HardwareToken"
        },
        "multiFactorSetting": {
                "inlineInitializeMissingPhone": false,
                "inlineInitializeMissingEmail": false,
                "inlineInitializeMissingKbAnswers": true,
                "inlineInitializeMissingPin": true,
                "enableAutoSubmitWhenAvailable": true,
                "otpLength": 6,
                "enableThrottling": true,
                "throttleMaxFailedAttempts": 5,
                "throttleInterval": 30,
                "throttleTimeUnit": "Minutes",
                "throttleAction": "BlockUseUntilTimeLimitExpires",
                "throttleStorageLocation": "AuxID1",
                "otpValidateThrottleCount": 5,
                "otpValidateThrottleInterval": 30
        },
        "registrationMethodOrder": [
                "YubiKey",
                "Email",
                "PushNotification",
                "KBQ",
                "Help",
                "PIN",
                "Phone",
                "OATH"
        ]
}

{
 "status": "Success",
 "message": []
}