Adaptive Authentication Realm Settings Endpoint

Introduction

Use the /adaptiveauth PATCH endpoint to enable and configure IP / Country Restrictions, IP Reputation / Threat Data, User / Group Restrictions, Geo-velocity, and User Risk policies / scores.

Prerequisites

1. (OPTIONAL) Have special SecureAuth IdP license to use IP Reputation / Threat Data analysis functionality / services for SecureAuth IdP version 9.1, or SecureAuth Threat Service analysis functionality / services for SecureAuth IdP version 9.2

Contact SecureAuth Support for more information or to upgrade

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

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

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

/adaptiveauth Endpoint

The following endpoint is 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

Adaptive Authentication Settings /adaptiveauth PATCH Endpoint

Use this endpoint to enable and configure the realm's adaptive authentication settings, including IP / Country Restriction, User / Group Restrictions, Geo-Velocity, IP Reputation / Threat Data, and User Risk.

HTTP Method	Endpoint	Example	SecureAuth IdP version
PATCH	/adaptiveauth	https://secureauth.company.com/api/v1/realms/26/adaptiveauth	9.1
PATCH	/adaptiveauth	https://secureauth.company.com/api/v2/realms/26/adaptiveauth	9.2

Adaptive Authentication v1 (SecureAuth IdP v9.1)

Field Definitions and Accepted Values for Configuration

Field	Description	Note
ipCountrySetting	Settings for IP / country restrictions
userGroupSetting	Settings for user / group restrictions
ipReputationThreatData	Settings for IP reputation threat data restrictions
geoVelocity	Settings for geo-velocity restrictions
userRisk *	Settings for user risk restrictions	* This field is only available in version 9.1 as long as the SecureAuth IdP appliance is not upgraded to version 9.2. This is because user risk is configured to use policies in version 9.1 and to use scores in version 9.2.
analyzeOrder	Order of restrictions to be analyzed per login	Accepted values, if enabled, in prioritized order: ipCountry ipReputationThreatData userGroup geoVelocity userRisk

NOTE: Defaulted Accepted Values appear in bold text in the table below.

userRisk fields – asterisked ( * ) in the table below – can only be used in version 9.1, as long as the SecureAuth IdP appliance is not upgraded to version 9.2. Note that an asterisked field which applies to ipCountrySetting, userGroupSetting, ipReputationThreatData, or geoVelocity is not affected by an upgrade to version 9.2 and can still be used.

Field	Description	Accepted Values	Applies to
enabled *	Enable Adaptive Authentication criterion	true false	ipCountrySetting userGroupSetting ipReputationThreatData geoVelocity userRisk
restrictionType	Information used for restriction	ip country	ipCountrySetting
restrictionType	Information used for restriction	user group	userGroupSetting
inListAction	Create list of selected restrictionType that is allowed or denied access to realm	Allow Deny	ipCountrySetting userGroupSetting
ipCountryList	List of allowed or denied IP addresses or countries based on restrictionType and inListAction values	Country codes must be listed in two-letter ISO format Accepted formats... IP addresses accepted in following formats, separated by comma: Specific IP address: e.g. 72.32.245.182 CIDR Notation: e.g. 72.32.245.0/24 IP range: e.g. 72.32.245.1-72.32.245.254 Multiple formats can be used on same line The following example entry is valid: 72.32.245.182,72.32.245.0/24,72.32.245.1-72.32.245.254	ipCountrySetting
failureAction	Action to take when login meets restriction criteria	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipCountrySetting userGroupSetting geoVelocity
failureActionRedirect	URL to which end-users are redirected if login meets restrictions	URL path	ipCountrySetting userGroupSetting geoVelocity For "FailureAction": "Redirect" configurations
requireUsernameBeforeAdaptive	Initiate IP / country and / or IP reputation analysis after end-user provides username	true false	ipCountrySetting ipReputationThreatData
userGroupList	List of allowed or denied IP addresses or countries based on restrictionType and inListAction values	any	userGroupSetting
extremeRiskAction	Action to take when login presents extreme risk	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipReputationThreatData
extremeRiskRedirect	URL to which end-users are redirected if login presents extreme risk	URL path	ipReputationThreatData For "extremeRiskAction": "Redirect" configurations
highRiskAction *	Action to take when login presents high risk	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipReputationThreatData userRisk
highRiskRedirect *	URL to which end-users are redirected if login presents high risk	URL path	ipReputationThreatData userRisk For "highRiskAction": "Redirect" configurations
mediumRiskAction *	Action to take when login presents medium risk	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipReputationThreatData userRisk
mediumRiskRedirect *	URL to which end-users are redirected if login presents medium risk	URL path	ipReputationThreatData userRisk For "mediumRiskAction": "Redirect" configurations
lowRiskAction *	Action to take when login presents low risk	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipReputationThreatData userRisk
lowRiskRedirect *	URL to which end-users are redirected if login presents low risk	URL path	ipReputationThreatData userRisk For "lowRiskAction": "Redirect" configurations
ipWhiteList	List of IP addresses that bypass the IP reputation threat data analysis	Accepted formats... IP addresses accepted in following formats, separated by comma: Specific IP address: e.g. 72.32.245.182 CIDR Notation: e.g. 72.32.245.0/24 IP range: e.g. 72.32.245.1-72.32.245.254 Multiple formats can be used on same line The following example entry is valid: 72.32.245.182,72.32.245.0/24,72.32.245.1-72.32.245.254	ipReputationThreatData
velocityLimit	Maximum speed in mph end-users could have traveled between last successful login and current login attempt	any, numerical	geoVelocity
highRiskFrom *	Range threshold for logins considered high risk	any, default 100	userRisk High risk login range from highRiskFrom value to infinity
mediumRiskFrom *	Range threshold for logins considered medium risk	any, default 50	userRisk Medium risk login range from mediumRiskFrom value to highRiskFrom value
lowRiskFrom *	Range threshold for logins considered low risk	any, default 0	userRisk Low risk login range from lowRiskFrom value to mediumRiskFrom value
noScoreAction *	Action to take when login presents no score	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	userRisk
noScoreRedirect *	URL to which end-users are redirected if login presents no score	URL path	userRisk For "noScoreAction": "Redirect" configurations
profileField *	SecureAuth Property mapped to the directory attribute that contains end-user's risk score to evaluate	Phone1 Phone2 Phone3 Phone4 Email1 Email2 Email3 Email4 AuxId1 AuxId2 AuxId3 AuxId4 AuxId5 AuxId6 AuxId7 AuxId8 AuxId9 AuxId10	userRisk

Parameters and Response Examples

Parameter

Success Response

{
	"ipCountrySetting": {
		"enabled": true,
		"restrictionType": "ip",
		"inListAction": "Allow",
		"ipCountryList": [<IP ADDRESS LIST>],
		"failureAction": "HardStop",
		"failureActionRedirect": null,
		"requireUsernameBeforeAdaptive": false
	},
	"userGroupSetting": {
		"enabled": true,
		"restrictionType": "user",
		"inListAction": "Deny",
		"userGroupList": [<USER LIST>],
		"failureAction": "TwoFactor",
		"failureActionRedirect": null
	},
	"ipReputationThreatData": {
		"enabled": true,
		"extremeRiskAction": "HardStop",
		"extremeRiskRedirect": null,
		"highRiskAction": "TwoFactor",
		"highRiskRedirect": null,
		"mediumRiskAction": "Redirect",
		"mediumRiskRedirect": "https://url.com",
		"lowRiskAction": "Continue",
		"lowRiskRedirect": null,
		"ipWhitelist": [<IP LIST>],
		"requireUsernameBeforeAdaptive": true
	},
	"geoVelocity": {
		"enabled": true,
		"velocityLimit": 500,
		"failureAction": "HardStop",
		"failureActionRedirect": null
	},
	"userRisk": {
		"enabled": true,
		"highRiskFrom": 100,
		"highRiskAction": "HardStop",
		"highRiskRedirect": null,
		"mediumRiskFrom": 50,
		"mediumRiskAction": "TwoFactor",
		"mediumRiskRedirect": null,
		"lowRiskFrom": 0,
		"lowRiskAction": "Continue",
		"lowRiskRedirect": null,
		"noScoreAction": "Disable",
		"noScoreRedirect": null,
		"profileField": "AuxId1"
	},
	"analyzeOrder": [
		"IpCountry"
		"IpReputationThreatData"
		"UserGroup"
		"GeoVelocity"
		"UserRisk"
	]
}

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

The userRisk parameters are only available on a SecureAuth IdP appliance running version 9.1 and can no longer be used if the appliance is upgraded to version 9.2

Adaptive Authentication v2 (SecureAuth IdP v9.2)

Field Definitions and Accepted Values for Configuration

Field	Description	Note
ipCountrySetting	Settings for IP / country restrictions
userGroupSetting	Settings for user / group restrictions
ipReputationThreatData	Settings for IP reputation threat data restrictions
geoVelocity	Settings for geo-velocity restrictions
userRisk	Settings for user risk restrictions
analyzeOrder	Order of restrictions to be analyzed per login	Accepted values, if enabled, in prioritized order: ipCountry ipReputationThreatData userGroup geoVelocity userRisk

NOTE: Defaulted Accepted Values appear in bold text in the table below

Field	Description	Accepted Values	Applies to
enabled	Enable Adaptive Authentication criterion	true false	ipCountrySetting userGroupSetting ipReputationThreatData geoVelocity userRisk
restrictionType	Information used for restriction	ip country	ipCountrySetting
restrictionType	Information used for restriction	user group	userGroupSetting
inListAction	Create list of selected restrictionType that is allowed or denied access to realm	Allow Deny	ipCountrySetting userGroupSetting
ipCountryList	List of allowed or denied IP addresses or countries based on restrictionType and inListAction values	Country codes must be listed in two-letter ISO format Accepted formats... IP addresses accepted in following formats, separated by comma: Specific IP address: e.g. 72.32.245.182 CIDR Notation: e.g. 72.32.245.0/24 IP range: e.g. 72.32.245.1-72.32.245.254 Multiple formats can be used on same line The following example entry is valid: 72.32.245.182,72.32.245.0/24,72.32.245.1-72.32.245.254	ipCountrySetting
failureAction	Action to take when login meets restriction criteria	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipCountrySetting userGroupSetting geoVelocity
failureActionRedirect	URL to which end-users are redirected if login meets restrictions	URL path	ipCountrySetting userGroupSetting geoVelocity For "FailureAction": "Redirect" configurations
requireUsernameBeforeAdaptive	Initiate IP / country and / or IP reputation analysis after end-user provides username	true false	ipCountrySetting ipReputationThreatData
userGroupList	List of allowed or denied IP addresses or countries based on restrictionType and inListAction values	any	userGroupSetting
extremeRiskAction	Action to take when login presents extreme risk	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipReputationThreatData
extremeRiskRedirect	URL to which end-users are redirected if login presents extreme risk	URL path	ipReputationThreatData For "extremeRiskAction": "Redirect" configurations
highRiskAction	Action to take when login presents high risk	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipReputationThreatData userRisk
highRiskRedirect	URL to which end-users are redirected if login presents high risk	URL path	ipReputationThreatData userRisk For "highRiskAction": "Redirect" configurations
mediumRiskAction	Action to take when login presents medium risk	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipReputationThreatData userRisk
mediumRiskRedirect	URL to which end-users are redirected if login presents medium risk	URL path	ipReputationThreatData userRisk For "mediumRiskAction": "Redirect" configurations
lowRiskAction	Action to take when login presents low risk	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	ipReputationThreatData userRisk
lowRiskRedirect	URL to which end-users are redirected if login presents low risk	URL path	ipReputationThreatData userRisk For "lowRiskAction": "Redirect" configurations
ipWhiteList	List of IP addresses that bypass the IP reputation threat data analysis	Accepted formats... IP addresses accepted in following formats, separated by comma: Specific IP address: e.g. 72.32.245.182 CIDR Notation: e.g. 72.32.245.0/24 IP range: e.g. 72.32.245.1-72.32.245.254 Multiple formats can be used on same line The following example entry is valid: 72.32.245.182,72.32.245.0/24,72.32.245.1-72.32.245.254	ipReputationThreatData
velocityLimit	Maximum speed in mph end-users could have traveled between last successful login and current login attempt	any, numerical	geoVelocity
noScoreAction	Action to take when login presents no score	HardStop Redirect TwoFactor SkipTwoFactor Continue Authenticated Disable	userRisk
noScoreRedirect	URL to which end-users are redirected if login presents no score	URL path	userRisk For "noScoreAction": "Redirect" configurations
providers	Entity supplying the User Risk Score	any	userRisk
name	Friendly name for the User Risk Score provider	any	provider
baseUrl	Root URL of the data server containing user profile information	Consistent portion of web address to which all endpoints are relative	provider
profileRelativeUrl	API endpoint relative URL path used to retrieve user profile information	Relative URL path should include /{username}	provider
authenticationMethod	How the connection is secured	Basic HTTP header is generated, containing the authentication credentials (username, password)	provider
username	Valid service account on the datastore that has permission to access and retrieve user profile information	any	provider
password	Password associated with the Username	any	provider
cookieUrl	API endpoint containing the relative URL path used in the authentication connection	Applicable to "authenticationMethod": "[cookie]" (actual parameter name / format depends on authenticationMethod list)	provider
requestIdField	Profile Property mapped to the directory attribute that contains the user’s ID required by the User Risk Score provider	Phone1 Phone2 Phone3 Phone4 Email1 Email2 Email3 Email4 AuxId1 AuxId2 AuxId3 AuxId4 AuxId5 AuxId6 AuxId7 AuxId8 AuxId9 AuxId10 UserId	provider
riskScoreJsonPath	Profile Field containing the User Risk Score JSON path	{xxx}{riskScore}	provider
rangeMax	Highest score a user can receive from User Risk Score provider	any, default 100	provider
rangeMin	Lowest score a user can receive from User Risk Score provider	any, default 0	provider
highRisk	Threshold for high risk user scores, i.e. a score from this numerical value to rangeMax is considered high risk	any, default 90	provider
mediumRisk	Threshold for medium risk user scores, i.e. a score from this numerical value to highRisk is considered medium risk	any, default 75	provider
deleteProvider	Remove User Risk Score provider from the system	false true	provider

Parameters and Response Examples

Parameter

Success Response

{
	"ipCountrySetting": {
		"enabled": true,
		"restrictionType": "ip",
		"inListAction": "Allow",
		"ipCountryList": [<IP ADDRESS LIST>],
		"failureAction": "HardStop",
		"failureActionRedirect": null,
		"requireUsernameBeforeAdaptive": false
	},
	"userGroupSetting": {
		"enabled": true,
		"restrictionType": "user",
		"inListAction": "Deny",
		"userGroupList": [<USER LIST>],
		"failureAction": "TwoFactor",
		"failureActionRedirect": null
	},
	"ipReputationThreatData": {
		"enabled": true,
		"extremeRiskAction": "HardStop",
		"extremeRiskRedirect": null,
		"highRiskAction": "TwoFactor",
		"highRiskRedirect": null,
		"mediumRiskAction": "Redirect",
		"mediumRiskRedirect": "https://url.com",
		"lowRiskAction": "Continue",
		"lowRiskRedirect": null,
		"ipWhitelist": [<IP LIST>],
		"requireUsernameBeforeAdaptiveAuth": true
	},
	"geoVelocity": {
		"enabled": true,
		"velocityLimit": 500,
		"failureAction": "HardStop",
		"failureActionRedirect": null
	},
    "userRisk": {
        "enabled": true,
        "providers": [
          {
            "enabled": true,
            "name": "",
            "baseUrl": "",
            "profileRelativeUrl": "",
            "authenticationMethod": "",
            "username": "",
            "password": "",
            "cookieUrl": "",
            "requestIdField": "",
            "riskScoreJsonPath": "",
            "rangeMax": 100,
            "rangeMin": 0,
            "highRisk": 90,
            "mediumRisk": 75,
            "deleteProvider": false
          }
        ],
        "highRiskAction": "HardStop",
        "highRiskRedirect": null,
        "mediumRiskAction": "TwoFactor",
        "mediumRiskRedirect": null,
        "lowRiskAction": "Continue",
        "lowRiskRedirect": null,
        "noScoreAction": "Disable",
        "noScoreRedirect": null
    }
	"analyzeOrder": [
		"IpCountry"
		"IpReputationThreatData"
		"UserGroup"
		"GeoVelocity"
		"UserRisk"
	]
}

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

Related Documentation

Adaptive Authentication Tab Configuration

Connecting Exabeam UEBA to SecureAuth IdP (version 9.1 and 9.2)

Connecting SailPoint IdentityIQ to SecureAuth IdP (version 9.1 and 9.2)

Adaptive Authentication API Guide

Content

Space Tools

Adaptive Authentication Settings /adaptiveauth PATCH Endpoint

Content

Space Tools

Breadcrumbs

Adaptive Authentication Realm Settings Endpoint

Adaptive Authentication Settings /adaptiveauth PATCH Endpoint