Documentation

Introduction

Use the /multifactor PATCH to enable and configure multi-factor authentication methods to use during login.

Prerequisites

1. Complete the Enablement and Header Steps in the Admin API Guide

2. Have access to the application code that calls to the API endpoint(s)

3. Integrate a membership and profile directory(s) with SecureAuth IdP (Data Realm Settings Endpoint)

4. (OPTIONAL) Integrate an SMTP Server for Email Multi-Factor Authentication methods (Overview Realm Settings Endpoint)

/multifactor Endpoint

The following endpoints are prepended with the URL, https://<SecureAuth IdP Domain>/api/v1/realms/<realm ID>, if running SecureAuth IdP v9.1 – in which realm ID is the ID number of the realm to configure –

or https://<SecureAuth IdP Domain>/api/v2/realms/<realm ID>, if running SecureAuth IdP v9.2 or later

Multi-Factor Authentication Settings /multifactor PATCH Endpoint

Use this endpoint to enable and configure the realm's multi-factor authentication methods used by end-users during login.

HTTP MethodEndpointExampleSecureAuth IdP version
PATCH
/multifactor
https://secureauth.company.com/api/v1/realms/26/multifactor
v9.1
PATCH
/multifactor
https://secureauth.company.com/api/v2/realms/26/multifactor
v9.2 or later
Field Definitions and Accepted Values for Configuration
FieldDescriptionAccepted ValuesNote
phoneSettingSettings for phone MFA methodsN / A 
field1 - field4Type of MFA method for designated phone field
  • LoginRequest
  • VoiceAndSmsText
  • SmsTextOnly
  • VoiceOnly
  • Disabled
 
phoneSmsSelectedDefault radio button selected on client-side MFA methods page
  • Voice
  • SmsText
If " field1" - "field4": "VoiceAndSmsText"
isVisibleDisplay both SMS and voice options even if both are not available
  • true
  • false
 
defaultCountryCodeAdd country code that appends to all phone numbers in directory that do not include country codeany 
maskRegex mask of phone numbers that display on client-side MFA methods pageanyPhone numbers are automatically masked as ***-***-1234
phoneBlockingSettings for phone number / type / carrier blockingN / A 
blockedSourcesList of types of phones blocked from accessing realm

Any of the following:

  • mobile
  • landline
  • virtual
  • landline_tollfree
  • landline_premium
  • pager
  • unknown
 
blockRecentlyChangedCarrierBlock phone numbers that have recently changed carriers to avoid ported phone login attempts
  • true
  • false
 
allowApproveDeleteRecentlyChangedCarrierEnable end-users to approve or delete carrier information when change is detected
  • true
  • false
If " blockRecentlyChangedCarrier": true
carrierStorageFieldSecureAuth IdP profile property mapped to directory attribute that contains carrier information
  • AuxId1
  • AuxId2
  • AuxId3
  • AuxId4
  • AuxId5
  • AuxId6
  • AuxId7
  • AuxId8
  • AuxId9
  • AuxId10
  • Email1
  • Email2
  • Email3
  • Email4
  • Phone1
  • Phone2
  • Phone3
  • Phone4
If " blockRecentlyChangedCarrier": true
enableBlockAllowListCreate a list of carriers and / or countries that are denied or only allowed access to realm
  • true
  • false
 
listActionWhether list of carriers and / or countries is allowed access or denied access to realm
  • Block
  • Allow
If "enableBlockAllowList": true
phoneCarriersList of carriers blocked or allowed access to realm, based on listAction valuesee 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

countryCountry origin of carriersee note
codeCarrier codesee note
nameCarrier namesee note
emailSettingSettings for email MFA methodsN / A 
field1 - field4Type of MFA method for designated email field
  • True
  • TrueTEXT
  • TrueHtmlLink
  • TrueTextLink
  • False
  • True: Email one-time passcode via HTML email
  • TrueTEXT: Email one-time passcode via Plain Text email
  • TrueHtmlLink: Email login request (link-to-accept) via HTML email
  • TrueTextLink: Email login request via Plain Text email
  • False: No method for email field
knowledgeBasedSettingSettings for knowledge based questions and answers MFA methodN / A 
enableQuestionsEnable KBQ / KBA MFA method
  • true
  • false
 
formatFormat and storage type of questions and answers in directory
  • Base64
  • Encryption
 
questionCountNumber of questions asked during authentication process
  • 1
  • 2
  • 3
 
doConversionConvert KBQs to certificate-based encryption from Base64 encoding
  • true
  • false
 
helpDeskSettingsSettings for help desk MFA methodN / A 
helpDesk1Settings for help desk option 1 MFA methodN / A 
helpDesk2Settings for help desk option 2 MFA methodN / A 
enabledEnable selected MFA method
  • true
  • false
For help desk, PIN, and OATH Passcode MFA method configurations
phonePhone number for help deskany 
emailEmail address for help deskany 
pinSettingSettings for personal identifying number (PIN) MFA methodN / A 
openPinDisplay PIN in directory as plain text
  • true
  • false
 
oneTimeUseOne-time use PIN that is immediately cleared from directory once used for authentication
  • true
  • false
Commonly used for first time user enrollment
showWhenEmptyDisplay one-time use PIN option on client-side login page even when value is empty
  • true
  • false
 
oathSettings for OATH passcode MFA methodN / A 
passcodeLengthNumber of digits composing OATH passcode
  • 6
  • 8
 
passcodeChangeIntervalNumber of seconds during which passcode is valid

number, defaulted to 60

 
passcodeOffsetNumber 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

 
pushNotificationSettings for push MFA methodsN / A 
requestTypeType of push method to use
  • Disabled
  • Passcode
  • AcceptDeny
  • PasscodeAndAcceptDeny
 
loginRequestTimeoutNumber of minutes during which login request is valid1 - 5 minutes 
acceptMethodType of login request response
  • AcceptButton
  • DisplaySymbol
 
companyNameName of company that displays on login requestany 
applicationNameName of application that displays on login requestany 
maxDeviceCountNumber of push tokens allowed per user account at single time

number, defaulted to -1

-1: no maximum amount
exceedingMaxCountActionAction to take when exceeding max token amount
  • AllowToReplace
  • NotAllowToReplace
If maxDeviceCount sets limit
replaceOrderByMethod to replace existing tokens with new ones when exceeding max amount
  • CreatedTime
  • LastAccessTime
If maxDeviceCount sets limit and " exceedingMaxCountAction": "AllowToReplace"
yubiKeySettingSettings for YubiKey MFA methodN / A 
enableYubiKeyAuthenticationEnable YubiKey as an MFA method
  • true
  • false
 
validateYubiKeyValidate YubiKey string via YubiCloud
  • true
  • false
 
storageLocationSecureAuth IdP profile property mapped to directory attribute that contains YubiKey provisioning information
  • HardwareToken
  • AuxId1
  • AuxId2
  • AuxId3
  • AuxId4
  • AuxId5
  • AuxId6
  • AuxId7
  • AuxId8
  • AuxId9
  • AuxId10
 
multiFactorSettingSettings for MFA workflowN / A 
inlineInitializeMissingPhoneAllow end-users to provide phone number information is phone MFA methods are enabled and directory has no phone data
  • true
  • false
 
inlineInitializeMissingEmailAllow end-users to provide email information is email MFA methods are enabled and directory has no email data
  • true
  • false
 
inlineInitializeMissingKbAnswersAllow end-users to provide KBA information is KBQ MFA methods are enabled and directory has no KBA data
  • true
  • false
 
inlineInitializeMissingPinAllow end-users to provide PIN information is PIN MFA method is enabled and directory has no PIN data
  • true
  • false
 
enableAutoSubmitWhenAvailableAutomatically submit MFA selection when only one MFA method is available
  • true
  • false
 
otpLengthNumber of digits comprising one-time passcode
  • 4
  • 5
  • 6
 
enableThrottlingEnable MFA method throttling
  • true
  • false
 
throttleMaxFailedAttemptsNumber of MFA entries allowed within throttleInterval period before throttleAction occurs

number, defaulted to 5

 
throttleIntervalAmount of time during which throttleMaxFailedAttempts is limitednumber, defaulted to 30 
throttleTimeUnitUnit of time for throttleInterval
  • Minutes
  • Hours
  • Days
 
throttleActionAction to take when throttleMaxFailed Attempts is reached during throttleInterval
  • BlockUseUntilTimeLimitExpires
  • LockUserAfterExceedingAttempts
 
throttleStorageLocationSecureAuth IdP profile property mapped to directory attribute that contains throttleMaxFailedAttempts count
  • AuxId1
  • AuxId2
  • AuxId3
  • AuxId4
  • AuxId5
  • AuxId6
  • AuxId7
  • AuxId8
  • AuxId9
  • AuxId10
  • Phone1
  • Phone2
  • Phone3
  • Phone4
  • Email1
  • Email2
  • Email3
  • Email4
  • Session
Session: Browser session, no directory storage
otpValidateThrottleCountNumber of MFA entry validations allowed within otpValidateThrottleInterval period before throttleAction occursnumber 
otpValidateThrottleIntervalNumber of minutes during which otpValidateThrottleCount is limitednumber 
registrationMethodOrderOrder of MFA methods displayed on client-side MFA methods page

Create list of enabled methods:

  • Phone
  • Email
  • KBQ
  • Help
  • PIN
  • OATH
  • PushNotification
  • YubiKey
  • VIPCredential **

See parameters for formatting

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

Parameters and Response Examples
ParametersSuccess Response
{
	"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": []
}
  • No labels