Documentation

Table of Contents


Other Resources


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

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 MethodURIExampleSecureAuth IdP version support
POST/api/v1/adaptauth
https://secureauth.company.com/secureauth2/api/v1/adaptauth
v9.1+
Definitions

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:

FunctionDescription
StatusConfigured Failure Action
Realm WorkflowWorkflow configured in the Web Admin
Suggested ActionSuggested next step to take based on the configurations

Status function and failure action

SecureAuth IdP provides these statuses for the associated failure actions

StatusDescription
ContinueEnd-user continues onto the configured workflow (Failure Action: Resume auth in Web Admin)
SkipTwoFactorEnd-user bypasses Multi-Factor Authentication and moves forward to next workflow step – for example: password (Failure Action: Step down auth in Web Admin)
TwoFactorEnd-user undergoes additional Multi-Factor Authentication (Failure Action: Step up auth in Web Admin)
AuthenticatedEnd-user is taken directly to post authentication target, bypassing additional analysis or Multi-Factor Authentication (Failure Action: Post auth in Web Admin)
HardStopEnd-user is stopped immediately in the workflow and cannot continue (Failure Action: Hard Stop in Web Admin)
RedirectEnd-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 ActionStatusDescription
2ndfactor_passwordContinueEnd-user must undergo Multi-Factor Authentication and then provide password
passwordSkipTwoFactorEnd-user must provide password
2ndfactorTwoFactorEnd-user must undergo Multi-Factor Authentication
noneAuthenticatedEnd-user is not required to perform authentication or password validation
stopHardStopEnd-user is stopped immediately in workflow and cannot continue
redirectRedirectEnd-user is redirected to the provided URL
POST endpoint JSON parameters and response examples
JSON ParametersSuccess ResponseFailure / Error Response
ContinueSkipTwoFactorTwoFactorAuthenticatedHardStopRedirect
{
    "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 MethodURIExampleSecureAuth IdP version support
POST/api/v1/accesshistory
https://secureauth.company.com/secureauth2/api/v1/accesshistory
v9.1+
POST endpoint JSON parameters and response examples
JSON ParametersSuccess ResponseFailure / 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

 

 

  • No labels