Documentation

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

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

Login request is blocked, thereby bypassing all workflows, remaining Adaptive Engine steps, and post authentication actions.

Redirect

Redirect to realm or URL

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

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

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

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

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

  1.  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.
  2. Complete the steps in the Authentication API Guide.
  3. Complete the Adaptive Authentication configuration steps in the SecureAuth IdP Web Admin – see Adaptive Authentication Tab Configuration.

    For the optional User Risk feature for Adaptive Authentication, refer to Connecting SailPoint IdentityIQ to SecureAuth IdP (version 9.1 and 9.2) or Connecting Exabeam UEBA to SecureAuth IdP (version 9.1 and 9.2).



SecureAuth IdP configuration steps

The steps to configure the Adaptive Authentication tab in SecureAuth IdP are in the Adaptive Authentication Tab Configuration document, 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 MethodURIExampleSecureAuth IdP version
POST/api/v1/adaptauth
https://secureauth.company.com/secureauth2/api/v1/adaptauth
v9.1+
Definitions

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.

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, e.g. 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, 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 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 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

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 MethodURIExampleSecureAuth IdP version
POST/api/v1/accesshistory
https://secureauth.company.com/secureauth2/api/v1/accesshistory
v9.1+
POST Endpoint JSON Parameters and Response Examples
JSON ParametersSuccess 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."
}



Related documentation

Adaptive Authentication Tab Configuration

Connecting Exabeam UEBA to SecureAuth IdP (version 9.1 and 9.2)

Connecting SailPoint IdentityIQ to SecureAuth IdP (version 9.1 and 9.2)

Adaptive Authentication Realm Settings Endpoint

  • No labels