Documentation

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 MethodEndpointExampleSecureAuth 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
FieldDescriptionNote

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.

FieldDescriptionAccepted ValuesApplies to

enabled *

Enable Adaptive Authentication criterion
  • true
  • false
  • ipCountrySetting
  • userGroupSetting
  • ipReputationThreatData
  • geoVelocity
  • userRisk
restrictionTypeInformation used for restriction
  • ip
  • country
  • ipCountrySetting
  • user
  • group
  • userGroupSetting
inListActionCreate list of selected restrictionType that is allowed or denied access to realm
  • Allow
  • Deny
  • ipCountrySetting
  • userGroupSetting
ipCountryListList of allowed or denied IP addresses or countries based on restrictionType and inListAction values

Country codes must be listed in two-letter ISO format

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
failureActionAction to take when login meets restriction criteria
  • HardStop
  • Redirect
  • TwoFactor
  • SkipTwoFactor
  • Continue
  • Authenticated
  • Disable
  • ipCountrySetting
  • userGroupSetting
  • geoVelocity
failureActionRedirectURL to which end-users are redirected if login meets restrictionsURL path
  • ipCountrySetting
  • userGroupSetting
  • geoVelocity

For "FailureAction": "Redirect" configurations

requireUsernameBeforeAdaptiveInitiate IP / country and / or IP reputation analysis after end-user provides username
  • true
  • false
  • ipCountrySetting
  • ipReputationThreatData
userGroupListList of allowed or denied IP addresses or countries based on restrictionType and inListAction valuesany
  • userGroupSetting
extremeRiskActionAction to take when login presents extreme risk
  • HardStop
  • Redirect
  • TwoFactor
  • SkipTwoFactor
  • Continue
  • Authenticated
  • Disable
  • ipReputationThreatData
extremeRiskRedirectURL to which end-users are redirected if login presents extreme riskURL 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 riskURL 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 riskURL 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 riskURL path
  • ipReputationThreatData
  • userRisk

For "lowRiskAction": "Redirect" configurations

ipWhiteListList of IP addresses that bypass the IP reputation threat data analysis

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
velocityLimitMaximum speed in mph end-users could have traveled between last successful login and current login attemptany, numerical
  • geoVelocity
highRiskFrom *Range threshold for logins considered high riskany, default 100
  • userRisk

High risk login range from highRiskFrom value to infinity

mediumRiskFrom *Range threshold for logins considered medium riskany, default 50
  • userRisk

Medium risk login range from mediumRiskFrom value to highRiskFrom value

lowRiskFrom *Range threshold for logins considered low riskany, 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 scoreURL 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
ParameterSuccess 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
FieldDescriptionNote

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

FieldDescriptionAccepted ValuesApplies to

enabled

Enable Adaptive Authentication criterion
  • true
  • false
  • ipCountrySetting
  • userGroupSetting
  • ipReputationThreatData
  • geoVelocity
  • userRisk
restrictionTypeInformation used for restriction
  • ip
  • country
  • ipCountrySetting
  • user
  • group
  • userGroupSetting
inListActionCreate list of selected restrictionType that is allowed or denied access to realm
  • Allow
  • Deny
  • ipCountrySetting
  • userGroupSetting
ipCountryListList of allowed or denied IP addresses or countries based on restrictionType and inListAction values

Country codes must be listed in two-letter ISO format

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
failureActionAction to take when login meets restriction criteria
  • HardStop
  • Redirect
  • TwoFactor
  • SkipTwoFactor
  • Continue
  • Authenticated
  • Disable
  • ipCountrySetting
  • userGroupSetting
  • geoVelocity
failureActionRedirectURL to which end-users are redirected if login meets restrictionsURL path
  • ipCountrySetting
  • userGroupSetting
  • geoVelocity

For "FailureAction": "Redirect" configurations

requireUsernameBeforeAdaptiveInitiate IP / country and / or IP reputation analysis after end-user provides username
  • true
  • false
  • ipCountrySetting
  • ipReputationThreatData
userGroupListList of allowed or denied IP addresses or countries based on restrictionType and inListAction valuesany
  • userGroupSetting
extremeRiskActionAction to take when login presents extreme risk
  • HardStop
  • Redirect
  • TwoFactor
  • SkipTwoFactor
  • Continue
  • Authenticated
  • Disable
  • ipReputationThreatData
extremeRiskRedirectURL to which end-users are redirected if login presents extreme riskURL path
  • ipReputationThreatData

For "extremeRiskAction": "Redirect" configurations

highRiskActionAction to take when login presents high risk
  • HardStop
  • Redirect
  • TwoFactor
  • SkipTwoFactor
  • Continue
  • Authenticated
  • Disable
  • ipReputationThreatData
  • userRisk
highRiskRedirectURL to which end-users are redirected if login presents high riskURL path
  • ipReputationThreatData
  • userRisk

For "highRiskAction": "Redirect" configurations

mediumRiskActionAction to take when login presents medium risk
  • HardStop
  • Redirect
  • TwoFactor
  • SkipTwoFactor
  • Continue
  • Authenticated
  • Disable
  • ipReputationThreatData
  • userRisk
mediumRiskRedirectURL to which end-users are redirected if login presents medium riskURL path
  • ipReputationThreatData
  • userRisk

For "mediumRiskAction": "Redirect" configurations

lowRiskActionAction to take when login presents low risk
  • HardStop
  • Redirect
  • TwoFactor
  • SkipTwoFactor
  • Continue
  • Authenticated
  • Disable
  • ipReputationThreatData
  • userRisk
lowRiskRedirectURL to which end-users are redirected if login presents low riskURL path
  • ipReputationThreatData
  • userRisk

For "lowRiskAction": "Redirect" configurations

ipWhiteListList of IP addresses that bypass the IP reputation threat data analysis

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
velocityLimitMaximum speed in mph end-users could have traveled between last successful login and current login attemptany, numerical
  • geoVelocity
noScoreActionAction to take when login presents no score
  • HardStop
  • Redirect
  • TwoFactor
  • SkipTwoFactor
  • Continue
  • Authenticated
  • Disable
  • userRisk
noScoreRedirectURL to which end-users are redirected if login presents no scoreURL path
  • userRisk

For "noScoreAction": "Redirect" configurations

providersEntity supplying the User Risk Scoreany
  • userRisk
nameFriendly name for the User Risk Score providerany
  • provider
baseUrlRoot URL of the data server containing user profile informationConsistent portion of web address to which all endpoints are relative
  • provider
profileRelativeUrlAPI endpoint relative URL path used to retrieve user profile information

Relative URL path should include /{username}

 

  • provider
authenticationMethodHow the connection is securedBasic 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
passwordPassword associated with the Usernameany
  • provider
cookieUrlAPI endpoint containing the relative URL path used in the authentication connectionApplicable to "authenticationMethod": "[cookie]" (actual parameter name / format depends on authenticationMethod list)
  • provider
requestIdFieldProfile 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
riskScoreJsonPathProfile Field containing the User Risk Score JSON path{xxx}{riskScore}
  • provider
rangeMaxHighest score a user can receive from User Risk Score providerany, default 100
  • provider
rangeMinLowest score a user can receive from User Risk Score providerany, default 0
  • provider
highRiskThreshold for high risk user scores, i.e. a score from this numerical value to rangeMax is considered high riskany, default 90
  • provider
mediumRiskThreshold for medium risk user scores, i.e. a score from this numerical value to highRisk is considered medium riskany, default 75
  • provider
deleteProviderRemove User Risk Score provider from the system
  • false
  • true
  • provider
Parameters and Response Examples
ParameterSuccess 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": []
}
  • No labels