Introduction

This guide explains how to configure the SecureAuth IdP Adaptive Authentication API endpoints for Adaptive Authentication workflows which analyze end-user login activity and effectively mitigate attacks from unauthorized users attempting to gain access to protected resources.

What's new in SecureAuth IdP version 9.3

Advanced adaptive capability powered by machine learning, available with the Prevent Threat Service license, enables machine learning for user risk score analysis.
Risk Ranges can be inverted to have a high score indicate a good user, and a low score indicate a risky user.

Previous Adaptive Authentication API guide

See Adaptive Authentication API Guide for the SecureAuth IdP v9.1 and v9.2 guide.

POST endpoints

The two Adaptive Authentication API endpoints are /adaptauth and /accesshistory which use the POST method.

/adaptauth

This 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.

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

The API utilizes 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 – for example: 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, for example 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

Failure / Error Response

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"
        }
}

The IP Address is not required if only performing user / group restriction; otherwise, it is required for all other functionality

{
  "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": ""
}

{
  "status": "disabled",
  "message": "Please enable the Analyze Engine within your SecureAuth realm."
}

{
  "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": ""
}

/accesshistory

This endpoint uses the POST method to create an end-user access history for geo-velocity calculations. Once 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.

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

JSON Parameters

Success Response

Failure / Error Response

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

Example:

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

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

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

Resources

Adaptive Authentication configuration

API configuration

Authentication API configuration