Adaptive Authentication API Guide

Use this guide to configure the SecureAuth Authentication API to use Adaptive Authentication workflows that use analysis to effectively mitigate attacks and unauthorized users from gaining access into sensitive resources.

SecureAuth IdP and Adaptive Authentication versions and corresponding features are provided next, in "Adaptive Authentication Action Definitions."

Adaptive Engine analyzes authentication requests to determine how to process each request. If the end user does not meet the analysis requirements, a Failure Action directs SecureAuth IdP to execute the appropriate action:

Failure Actions	Results
Disable Continue Adaptive Authentication	No action... The specific Adaptive Engine check is not executed. The next step in Adaptive Engine is performed, or, if all Adaptive Authentication steps are completed, the end user is taken through any additional configured workflow steps.
Hard Stop Refuse authentication request	Workflow is stopped immediately... Login request is blocked, thereby bypassing all workflows, remaining Adaptive Engine steps, and post authentication actions.
Redirect Redirect to realm or URL	End-user is redirected to the URL provided in the field (e.g. another SecureAuth IdP realm)... Adaptive Engine is exited and end user is redirected to an alternate URL or realm to continue with an alternate workflow, thereby bypassing all workflows and remaining Adaptive Engine steps.
Step up auth Require two-factor authentication	Additional authentication is required... Adaptive Engine is exited and end user continues through the workflow, bypassing the persistent token check such as Device Recognition / Fingerprint, Cookie or Certificate, and forcing 2-Factor Authentication as defined in the workflow.
Step down auth Skip two-factor authentication	End-user is taken to the next workflow step, bypassing additional analysis and any 2-Factor Authentication steps... Adaptive Engine is exited and end user bypasses remaining Adaptive Engine steps, persistent token check, and 2-Factor Authentication check. Most commonly, the end user will be required to enter a password, provided the workflow is configured for this entry.
Resume Resume authentication workflow	End-user is taken through any additional configured workflow steps (2-Factor Authentication), bypassing remaining analysis steps... Adaptive Engine is exited and the next step in the workflow is performed such as a persistent token check or 2-Factor Authentication .
Post auth Skip to post-authentication	End-user is taken to the post-authentication target (IdM page, application, etc.), bypassing additional analysis and configured workflow steps... Adaptive Engine is exited and end user is taken to the post authentication target (such as Identity Management page or application), thereby bypassing all workflows and remaining Adaptive Engine steps, as well as a password check, if the workflow is configured for this entry.

Prerequisites

Optional: Have special SecureAuth IdP license to use IP Reputation / Threat Data analysis functionality or services.
Contact SecureAuth Support for more information or to upgrade.
Complete the steps in the Authentication API guide.
Complete the Adaptive Authentication configuration steps in the SecureAuth IdP Web Admin – see Adaptive Authentication Tab Configuration topic.
For the optional User Risk feature for Adaptive Authentication, refer to Connecting SailPoint IdentityIQ to SecureAuth IdP or Connecting Exabeam UEBA to SecureAuth IdP topics.

SecureAuth IdP configuration steps

The steps to configure the Adaptive Authentication tab in SecureAuth IdP are in the Adaptive Authentication Tab Configuration topic, in the SecureAuth IdP Configuration Steps section. You can select the instructions for SecureAuth IdP v9.1 or SecureAuth IdP v9.2.

Endpoints

The /adaptauth endpoint uses the POST method to enable SecureAuth IdP Adaptive Authentication to analyze an end user's profile, group, IP address, country, geo-velocity, and any risks detected by threat intelligence data.

The /accesshistory endpoint uses the POST method to create an end user access history for geo-velocity calculations.

After the end user is authenticated, the information is posted to the endpoint, and a new entry is created and stored in the end user profile.

On the next login attempt, SecureAuth IdP uses the stored information to validate whether the distance traveled from the previous login to the current attempt is feasible.

POST

/adaptauth

HTTP Method	URI	Example	SecureAuth IdP version
POST	`/api/v1/adaptauth`	https://secureauth.company.com/secureauth2/api/v1/adaptauth	v9.1+

The API uses the information configured in the Adaptive Authentication / Workflow section of the SecureAuth IdP Web Admin.

Functions

SecureAuth IdP returns a response that contains these functions.

Function	Description
Status	Configured Failure Action
Realm Workflow	Workflow configured in the Web Admin
Suggested Action	Suggested next step to take based on the configurations

Status Function and Failure Action

SecureAuth IdP provides these statuses for the associated failure actions.

Status	Description
Continue	End user continues onto the configured workflow (Failure Action: Resume auth in Web Admin)
SkipTwoFactor	End user bypasses multi-factor authentication and moves forward to next workflow step, e.g. password (Failure Action: Step down auth in Web Admin)
TwoFactor	End user undergoes additional multi-factor authentication (Failure Action: Step up auth in Web Admin)
Authenticated	End user is taken directly to post authentication target, bypassing additional analysis or multi-factor authentication (Failure Action: Post auth in Web Admin)
HardStop	End user is stopped immediately in the workflow and cannot continue (Failure Action: Hard Stop in Web Admin)
Redirect	End user is redirected to URL provided, e.g. another SecureAuth IdP realm (Failure Action: Redirect in Web Admin)

Suggested Action

SecureAuth IdP provides these suggested actions for the associated statuses.

Suggested Action	Status	Description
2ndfactor_password	Continue	End user must undergo multi-factor authentication and then provide password
password	SkipTwoFactor	End user must provide password
2ndfactor	TwoFactor	End user must undergo multi-factor authentication
none	Authenticated	End user is not required to perform authentication or password validation
stop	HardStop	End user is stopped immediately in workflow and cannot continue
redirect	Redirect	End user is redirected to the provided URL

JSON Parameters	Success Response*
JSON Parameters	Continue	SkipTwoFactor	TwoFactor	Authenticated	HardStop	Redirect
{ "user_id": "<USERNAME>", "parameters": { "ip_address": "<IP ADDRESS>" } } Example: { "user_id": "jsmith", "parameters": { "ip_address": "111.222.33.44" } } Notice The IP Address is not required if only performing user / group restriction; otherwise, it is required for all other functionality Failure / Error Response: { "status": "disabled", "message": "Please enable the Analyze Engine within your SecureAuth realm." }	{ "realm_workflow": "username_2ndfactor_password", "suggested_action": "2ndfactor_password", "status": "Continue", "message": "" }	{ "realm_workflow": "username_2ndfactor_password", "suggested_action": "password", "status": "SkipTwoFactor", "message": "" }	{ "realm_workflow": "username_2ndfactor_password", "suggested_action": "2ndfactor_password", "status": "TwoFactor", "message": "" }	{ "realm_workflow": "username_2ndfactor_password", "suggested_action": "none", "status": "Authenticated", "message": "" }	{ "realm_workflow": "username_2ndfactor_password", "suggested_action": "stop", "status": "HardStop", "message": "" }	{ "realm_workflow": "username_2ndfactor_password", "suggested_action": "redirect", "redirect_url": "https://example.com", "status": "IPRedirect", "message": "" }
	{ "realm_workflow": "username_password", "suggested_action": "password", "status": "Continue", "message": "" }	{ "realm_workflow": "username_password", "suggested_action": "password", "status": "SkipTwoFactor", "message": "" }	{ "realm_workflow": "username_password", "suggested_action": "2ndfactor_password", "status": "TwoFactor", "message": "" }	{ "realm_workflow": "username_password", "suggested_action": "none", "status": "Authenticated", "message": "" }	{ "realm_workflow": "username_password", "suggested_action": "stop", "status": "HardStop", "message": "" }	{ "realm_workflow": "username_password", "suggested_action": "redirect", "redirect_url": "https://example.com", "status": "IPRedirect", "message": "" }
	{ "realm_workflow": "2ndfactor", "suggested_action": "2ndfactor", "status": "Continue", "message": "" }	{ "realm_workflow": "2ndfactor", "suggested_action": "none", "status": "SkipTwoFactor", "message": "" }	{ "realm_workflow": "2ndfactor", "suggested_action": "2ndfactor", "status": "TwoFactor", "message": "" }	{ "realm_workflow": "2ndfactor", "suggested_action": "none", "status": "Authenticated", "message": "" }	{ "realm_workflow": "2ndfactor", "suggested_action": "stop", "status": "HardStop", "message": "" }	{ "realm_workflow": "2ndfactor", "suggested_action": "redirect", "redirect_url": "https://example.com", "status": "IPRedirect", "message": "" }
	{ "realm_workflow": "usernamepassword_2ndfactor", "suggested_action": "2ndfactor", "status": "Continue", "message": "" }	{ "realm_workflow": "usernamepassword_2ndfactor", "suggested_action": "none", "status": "SkipTwoFactor", "message": "" }	{ "realm_workflow": "usernamepassword_2ndfactor", "suggested_action": "2ndfactor", "status": "TwoFactor", "message": "" }	{ "realm_workflow": "usernamepassword_2ndfactor", "suggested_action": "none", "status": "Authenticated", "message": "" }	{ "realm_workflow": "usernamepassword_2ndfactor", "suggested_action": "stop", "status": "HardStop", "message": "" }	{ "realm_workflow": "usernamepassword_2ndfactor", "suggested_action": "redirect", "redirect_url": "https://example.com", "status": "IPRedirect", "message": "" }
	{ "realm_workflow": "usernamepassword", "suggested_action": "password", "status": "Continue", "message": "" }	{ "realm_workflow": "usernamepassword", "suggested_action": "none", "status": "SkipTwoFactor", "message": "" }	{ "realm_workflow": "usernamepassword", "suggested_action": "2ndfactor", "status": "TwoFactor", "message": "" }	{ "realm_workflow": "usernamepassword", "suggested_action": "none", "status": "Authenticated", "message": "" }	{ "realm_workflow": "usernamepassword", "suggested_action": "stop", "status": "HardStop", "message": "" }	{ "realm_workflow": "usernamepassword", "suggested_action": "redirect", "redirect_url": "https://example.com", "status": "IPRedirect", "message": "" }
	{ "realm_workflow": "username", "suggested_action": "none", "status": "Continue", "message": "" }	{ "realm_workflow": "username", "suggested_action": "none", "status": "SkipTwoFactor", "message": "" }	{ "realm_workflow": "username", "suggested_action": "2ndfactor", "status": "TwoFactor", "message": "" }	{ "realm_workflow": "username", "suggested_action": "none", "status": "Authenticated", "message": "" }	{ "realm_workflow": "username", "suggested_action": "stop", "status": "HardStop", "message": "" }	{ "realm_workflow": "username", "suggested_action": "redirect", "redirect_url": "https://example.com", "status": "IPRedirect", "message": "" }
	{ "realm_workflow": "persistent_token", "suggested_action": "none", "status": "Continue", "message": "" }	{ "realm_workflow": "persistent_token", "suggested_action": "none", "status": "SkipTwoFactor", "message": "" }	{ "realm_workflow": "persistent_token", "suggested_action": "2ndfactor", "status": "TwoFactor", "message": "" }	{ "realm_workflow": "persistent_token", "suggested_action": "none", "status": "Authenticated", "message": "" }	{ "realm_workflow": "persistent_token", "suggested_action": "stop", "status": "HardStop", "message": "" }	{ "realm_workflow": "persistent_token", "suggested_action": "redirect", "redirect_url": "https://example.com", "status": "IPRedirect", "message": "" }

* You might receive a DisabledContinue state, depending on how you have configured adaptive authentication. You can treat this state the same as the Continue state. If you receive the DisabledContinue state, please open a SecureAuth Support ticket (option: "I have a question or issue regarding SecureAuth Identity Platform") and enter the exact adaptive configuration you have set in the Identity Platform realm.

/accesshistory

HTTP Method	URI	Example	SecureAuth IdP version
POST	`/api/v1/accesshistory`	https://secureauth.company.com/secureauth2/api/v1/accesshistory	v9.1+

JSON Parameters	Success Response
{ "user_id": "<USERNAME>", "ip_address": "<IP ADDRESS>" } Example: { "user_id": "jsmith", "ip_address"; "111.222.33.44" } Failure / Error Response: { "status": "invalid", "message": "Access History was not saved." }	{ "status": "valid", "message": "Access History request has been processed." }

JSON Parameters

Success Response

{
    "user_id": "<USERNAME>",
    "ip_address": "<IP ADDRESS>"
}

Example:

{
"user_id": "jsmith",
"ip_address"; "111.222.33.44"
}

Failure / Error Response:

{
"status": "invalid",
"message": "Access History was not saved."
}

{
  "status": "valid",
  "message": "Access History request has been processed."
}

In this section: