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.
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)
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 |
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:
|
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 |
|
|
restrictionType | Information used for restriction |
|
|
|
| ||
inListAction | Create list of selected restrictionType that is allowed or denied access to realm |
|
|
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:
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 |
|
failureAction | Action to take when login meets restriction criteria |
|
|
failureActionRedirect | URL to which end-users are redirected if login meets restrictions | URL path |
For "FailureAction": "Redirect" configurations |
requireUsernameBeforeAdaptive | Initiate IP / country and / or IP reputation analysis after end-user provides username |
|
|
userGroupList | List of allowed or denied IP addresses or countries based on restrictionType and inListAction values | any |
|
extremeRiskAction | Action to take when login presents extreme risk |
|
|
extremeRiskRedirect | URL to which end-users are redirected if login presents extreme risk | URL path |
For "extremeRiskAction": "Redirect" configurations |
highRiskAction * | Action to take when login presents high risk |
|
|
highRiskRedirect * | URL to which end-users are redirected if login presents high risk | URL path |
For "highRiskAction": "Redirect" configurations |
mediumRiskAction * | Action to take when login presents medium risk |
|
|
mediumRiskRedirect * | URL to which end-users are redirected if login presents medium risk | URL path |
For "mediumRiskAction": "Redirect" configurations |
lowRiskAction * | Action to take when login presents low risk |
|
|
lowRiskRedirect * | URL to which end-users are redirected if login presents low risk | URL path |
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:
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 |
|
velocityLimit | Maximum speed in mph end-users could have traveled between last successful login and current login attempt | any, numerical |
|
highRiskFrom * | Range threshold for logins considered high risk | any, default 100 |
High risk login range from highRiskFrom value to infinity |
mediumRiskFrom * | Range threshold for logins considered medium risk | any, default 50 |
Medium risk login range from mediumRiskFrom value to highRiskFrom value |
lowRiskFrom * | Range threshold for logins considered low risk | any, default 0 |
Low risk login range from lowRiskFrom value to mediumRiskFrom value |
noScoreAction * | Action to take when login presents no score |
|
|
noScoreRedirect * | URL to which end-users are redirected if login presents no score | URL path |
For "noScoreAction": "Redirect" configurations |
profileField * | SecureAuth Property mapped to the directory attribute that contains end-user's risk score to evaluate |
|
|
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" ] } | { |
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
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:
|
NOTE: Defaulted Accepted Values appear in bold text in the table below
Field | Description | Accepted Values | Applies to |
---|---|---|---|
enabled | Enable Adaptive Authentication criterion |
|
|
restrictionType | Information used for restriction |
|
|
|
| ||
inListAction | Create list of selected restrictionType that is allowed or denied access to realm |
|
|
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:
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 |
|
failureAction | Action to take when login meets restriction criteria |
|
|
failureActionRedirect | URL to which end-users are redirected if login meets restrictions | URL path |
For "FailureAction": "Redirect" configurations |
requireUsernameBeforeAdaptive | Initiate IP / country and / or IP reputation analysis after end-user provides username |
|
|
userGroupList | List of allowed or denied IP addresses or countries based on restrictionType and inListAction values | any |
|
extremeRiskAction | Action to take when login presents extreme risk |
|
|
extremeRiskRedirect | URL to which end-users are redirected if login presents extreme risk | URL path |
For "extremeRiskAction": "Redirect" configurations |
highRiskAction | Action to take when login presents high risk |
|
|
highRiskRedirect | URL to which end-users are redirected if login presents high risk | URL path |
For "highRiskAction": "Redirect" configurations |
mediumRiskAction | Action to take when login presents medium risk |
|
|
mediumRiskRedirect | URL to which end-users are redirected if login presents medium risk | URL path |
For "mediumRiskAction": "Redirect" configurations |
lowRiskAction | Action to take when login presents low risk |
|
|
lowRiskRedirect | URL to which end-users are redirected if login presents low risk | URL path |
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:
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 |
|
velocityLimit | Maximum speed in mph end-users could have traveled between last successful login and current login attempt | any, numerical |
|
noScoreAction | Action to take when login presents no score |
|
|
noScoreRedirect | URL to which end-users are redirected if login presents no score | URL path |
For "noScoreAction": "Redirect" configurations |
providers | Entity supplying the User Risk Score | any |
|
name | Friendly name for the User Risk Score provider | any |
|
baseUrl | Root URL of the data server containing user profile information | Consistent portion of web address to which all endpoints are relative |
|
profileRelativeUrl | API endpoint relative URL path used to retrieve user profile information | Relative URL path should include /{username}
|
|
authenticationMethod | How the connection is secured | Basic HTTP header is generated, containing the authentication credentials (username, password) |
|
username | Valid service account on the datastore that has permission to access and retrieve user profile information | any |
|
password | Password associated with the Username | any |
|
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) |
|
requestIdField | Profile Property mapped to the directory attribute that contains the user’s ID required by the User Risk Score provider |
|
|
riskScoreJsonPath | Profile Field containing the User Risk Score JSON path | {xxx}{riskScore} |
|
rangeMax | Highest score a user can receive from User Risk Score provider | any, default 100 |
|
rangeMin | Lowest score a user can receive from User Risk Score provider | any, default 0 |
|
highRisk | Threshold for high risk user scores, i.e. a score from this numerical value to rangeMax is considered high risk | any, default 90 |
|
mediumRisk | Threshold for medium risk user scores, i.e. a score from this numerical value to highRisk is considered medium risk | any, default 75 |
|
deleteProvider | Remove User Risk Score provider from the system |
|
|
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" ] } | { |