Documentation

Introduction

SecureAuth's Authentication API embeds the SecureAuth IdP functionality into a custom application, enabling flexible workflow configurations and user interfaces. Using a RESTful API encrypted over SSL, SecureAuth IdP can validate user IDs, passwords, PINs, soft tokens, Push-to-Accept responses, and knowledge-based answers; can generate One-time Passwords (OTPs) delivered via phone call, SMS message, email message, help desk, or Push / Push-to-Accept Notification; can analyze a user's access attempt through SecureAuth's Device / Browser Fingerprinting and Adaptive Authentication; and can evaluate IP address risk through threat intelligence data.

Each SecureAuth IdP realm can host its own uniquely configured Authentication API, enabling various workflows and registration methods.

By simply integrating an application with SecureAuth's Authentication API, enabling 2-Factor Authentication mechanisms, and configuring Adaptive Authentication, customers can securely direct users through unique logins and interfaces without leaving the application.

NOTE: This Authentication API Guide is specifically for SecureAuth IdP 8.2+; refer to Authentication API 8.1 Configuration Guide for version 8.1 functionality

Prerequisites

1. Have access to the application code

2. Have an on-premises directory with which SecureAuth IdP can integrate

3. Create a New Realm or access an existing realm in which the Authentication API will be enabled

The API can be included in any realm with any Post Authentication event as long as the appropriate directory is integrated, the registration methods are enabled for 2-Factor Authentication use, adaptive authentication settings are in place, and device fingerprinting configurations are completed (if using all features)

4. Configure the Data tab in the SecureAuth IdP Web Admin

A directory integration is required for SecureAuth IdP to pull user profile information during the login process

Ensure that the Registration Methods Profile Properties (e.g. Phone 1, Email 1, etc.) are accurately mapped to directory attributes to enable 2-Factor Authentication workflows

SecureAuth IdP Web Admin
Workflow

 

1. In the Adaptive Authentication section, configure the realm to enable / disable functions to be used by the application

Refer to Adaptive Authentication Configuration Guide (version 8.2) for the full configuration steps

If enabling the Adaptive Authentication features, be sure to select the preferred Authentication Mode (in the Workflow section), as it is used with the suggested actions by the API

If not using the /adaptauth endpoint, then no configuration is required

Browser / Mobile Device Digital Fingerprinting

 

2. Configure the Device / Browser Fingerprinting settings to enable the use of /dfp endpoints

Refer to Device / Browser Fingerprinting - Heuristic-based Authentication for the full configuration steps

If not using the /dfp endpoints, then no configuration is required

Click Save once the configurations have been completed and before leaving the Workflow page to avoid losing changes

Registration Methods

 

3. In the Registration Configuration section, enable at least one 2-Factor Authentication mechanism to be utilized in the Authentication API workflow

Refer to Registration Methods Tab Configuration for more information

If not using 2-Factor Authentication in the workflow, then no configuration is required

The Authentication API supports the following registration methods:

  • Telephony OTP
  • SMS OTP
  • Email OTP
  • Knowledge-based Questions and Answers
  • Help Desk
  • OATH Token
  • Push Notification and Push-to-Accept
  • Static PIN

Ensure that the Registration Methods Profile Properties (e.g. Phone 1, Email 1, etc.) are mapped appropriately to directory attributes in the Data tab to enable 2-Factor Authentication

Authentication API

 

4. Check Enable in the API Settings section

5. Click Generate App ID / Key to create a new Application ID and Application Key

The Application ID and Application Key are unique per realm

6. Click Select & Copy to copy the contents from the fields

These values will be required in the HTTP Header configuration steps below

Click Save once the configurations have been completed and before leaving the Registration Methods page to avoid losing changes

HTTP Header

To authenticate against the API, an HTTP basic authorization header and Content-Type header are required.

1. Add a Content-Type header with a value of application/json

2. Create an Authorization Header for all requests by following the steps below

Authorization Header

For GET endpoint:

1. Build a string based on the request

  • METHOD (GET)
  • DATE/TIME
  • APPLICATION ID (from SecureAuth IdP Web Admin)
  • PATH (API endpoint, e.g. /secureauth2/api/v1/users/<userID>/factors)

2. Create an HMAC SHA256 hash of step 1 using the Application Key (from SecureAuth IdP Web Admin)

3. Encode the HMAC SHA256 hash from step 2 in Base64

4. Concatenate the "Application ID", ":", and the "Base64 encoded HMAC SHA256 hash" from step 3

ApplicationID:Base64EncodedHMACSHA256Hash

5. Encode the value from step 4 in Base64

6. Concatenate "Basic " and the "Value of Step 5"

Basic Step5Value
 

GET Request Example
Step 1
    GET
    Wed, 08 Apr 2015 21:37:33 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /secureauth2/api/v1/users/jbeam/factors

End Result: "GET\nWed, 08 Apr 2015 21:37:33 GMT\n1b700d2e7b7b4abfa1950c865e23e81a\n/secureauth2/api/v1/users/jbeam/factors"

Step 3
    F5yqdLDJddUYOlrpBlOJBh/YCUIMVCsWejuhiCrqMmw=

Step 4
    1b700d2e7b7b4abfa1950c865e23e81a:F5yqdLDJddUYOlrpBlOJBh/YCUIMVCsWejuhiCrqMmw=

Step 5
    MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOnorVGNYNG4vbFlsTmNvNjRpQkRENVJKaHFiZ0h0UGYwaEQ4d1d4bTgvWVk9

Step 6
    Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOnorVGNYNG4vbFlsTmNvNjRpQkRENVJKaHFiZ0h0UGYwaEQ4d1d4bTgvWVk9

End Result:
    Method: GET, 
    RequestUri: 'https://secureauth.company.com/secureauth2/api/v1/users/jbeam/factors', 
    Version: 1.1, 
    Headers: {
        Connection: Keep-Alive  
        Date: Wed, 08 Apr 2015 21:37:33 GMT  
        Authorization: Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkY1eXFkTERKZGRVWU9scnBCbE9KQmgvWUNVSU1WQ3NXZWp1aGlDcnFNbXc9  
        Host: secureauth.company.com  
        Content-Length: 0
    }

For POST endpoint:

1. Build a string based on the request

  • METHOD (POST)
  • DATE/TIME
  • APPLICATION ID (from SecureAuth IdP Web Admin)
  • PATH (API endpoint, e.g. /secureauth2/api/v1/auth)
  • CONTENT (JSON Parameters)

2. Create an HMAC SHA256 hash of step 1 using the Application Key (from SecureAuth IdP Web Admin)

3. Encode the HMAC SHA256 hash from step 2 in Base64

4. Concatenate the "Application ID", ":", and the "Base64 encoded HMAC SHA256 hash" from step 3

ApplicationID:Base64EncodedHMAC256Hash

5. Encode the value from step 4 in Base64

6. Concatenate "Basic " and the "Value of Step 5"

Basic Step5Value
 

POST Request Example
Step 1
    POST
    Wed, 08 Apr 2015 21:27:30 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /secureauth2/api/v1/auth
    {"user_id":"jbeam","type":"user_id"}

End Result: "POST\nWed, 08 Apr 2015 21:27:30 GMT\n1b700d2e7b7b4abfa1950c865e23e81a\n/secureauth2/api/v1/auth\n{"user_id":"jbeam","type":"user_id"}"

Step 3
    D6nkepAEtk/M+cpkyWQ/hZMXZxPJ32L++5ZZa6+pB8U=

Step 4
    1b700d2e7b7b4abfa1950c865e23e81a:D6nkepAEtk/M+cpkyWQ/hZMXZxPJ32L++5ZZa6+pB8U=

Step 5
    MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkQ2bmtlcEFFdGsvTStjcGt5V1EvaFpNWFp4UEozMkwrKzVaWmE2K3BCOFU9

Step 6
    Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkQ2bmtlcEFFdGsvTStjcGt5V1EvaFpNWFp4UEozMkwrKzVaWmE2K3BCOFU9

End Result:
    Method: POST
    RequestUri: 'https://secureauth.company.com/secureauth2/api/v1/auth'
    Version: 1.1
    Headers: {
        Connection: Keep-Alive  
        Date: Wed, 08 Apr 2015 21:27:30 GMT  
        Authorization: Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkQ2bmtlcEFFdGsvTStjcGt5V1EvaFpNWFp4UEozMkwrKzVaWmE2K3BCOFU9  
        Expect: 100-continue  
        Host: secureauth.company.com  
        Content-Length: 36  
        Content-Type: application/json; charset=utf-8
    }

When an Authorization Header cannot be validated, one of the following responses will be returned:

{
"status": "invalid",
"message": "Missing authentication header.",
}
{
"status": "invalid",
"message": "Unknown authentication scheme.",
}
{
"status": "invalid",
"message": "Clock skew of message is outside threshold.",
}
{
"status": "invalid",
"message": "AppId is unknown.",
}
{
"status": "invalid",
"message": "Authentication header value is empty.",
}
{
"status": "invalid",
"message": "Authentication header has been seen before.",
}
{
"status": "invalid",
"message": "Authentication header value's format should be 'appId:hash'.",
}
{
"status": "invalid",
"message": "Invalid credentials.",
}

3. (OPTIONAL) If utilizing the Email 2-Factor Authentication method and a different language than US English, create an Accept-Language header to generate the Email OTP messages in the preferred language

If no Accept-Language header is present, the Email OTP messages default to US English

/users Endpoint

Endpoint: https:// SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/users/<username>/factors

For example: https://secureauth.company.com/secureauth2/api/v1/users/jbeam/factors

The /users GET endpoint provides to the end-user the list of enabled 2-Factor Authentication methods. By utilizing the username in the endpoint URL, SecureAuth IdP can access the user's profile and respond with the list of available 2-Factor Authentication mechanisms.

As a GET endpoint, there is no body, so no JSON parameters are required.

Definitions

status: The status of user ID provided (found, not_found, invalid, etc.); will always be in response

message: Additional information regarding the status; will always be in response

user_id: The user ID provided; will always be in response, whether successful or not

factors: The list of available multi-factor authentication methods available to the user

  • type: The type of method (phone, kbq, push, etc.)
  • id: The SecureAuth IdP Profile Property that is mapped to the directory field containing the information required to conduct the authentication (Phone1, Email2, etc.)
    • The indexed knowledge-based questions within the Knowledge-based Questions SecureAuth IdP Property (KBQ1, KBQ2, etc.)
    • A unique identifier provided to SecureAuth IdP by the mobile device during the provisioning process (for OATH and Push)
  • value: The information contained in the SecureAuth IdP Property / directory field (phone number, email address, device name, etc.)
  • capabilities: The variations available for the factor that require user selection (phone call, text message, etc.)

Response:

SuccessFail / Error
{
  "status": "found",
  "message": "",
  "user_id": "jbeam",
  "factors": [
    {
      "type": "phone",
      "id": "Phone1",
      "value": "123-456-7890",
      "capabilities": [
        "call"
      ]
    },
    {
      "type": "phone",
      "id": "Phone2",
      "value": "987-654-3210",
      "capabilities": [
        "sms",
        "call"
      ]
    },
    {
      "type": "email",
      "id": "Email1",
      "value": "jbeam@company.com"
    },
    {
      "type": "kbq",
      "id": "KBQ1",
      "value": "What city were you born in?"
    },
    {
      "type": "kbq",
      "id": "KBQ2",
      "value": "What was your favorite childhood game?"
    },
    {
      "type": "kbq",
      "id": "KBQ3",
      "value": "What was your dream job as a child?"
    },
    {
      "type": "kbq",
      "id": "KBQ4",
      "value": "Who is your personal hero?"
    },
    {
      "type": "kbq",
      "id": "KBQ5",
      "value": "What is the last name of your favorite school teacher?"
    },
    {
      "type": "kbq",
      "id": "KBQ6",
      "value": "What is the name of your favorite childhood pet?"
    },
    {
      "type": "help_desk",
      "id": "HelpDesk1",
      "value": "987-654-3210"
    },
    {
      "type": "help_desk",
      "id": "HelpDesk2",
      "value": "987-654-3211"
    },
    {
"type": "push",
"id": "8117b62897734d71b48ecdcab19bd437",
"value": "HTC One",
"capabilities": [
"push",
"push_accept"
]
},
{
"type": "oath",
"id": "63c6b390cac04efb8d283828ed29c120",
"value": "SecureAuth OTP Mobile App"
},
{
"type": "pin",
"value": "Private PIN"
}
],
"status": "found",
"message": "",
"user_id": "jbeam"
}
{
  "status": "not_found",
  "message": "User Id was not found"
}
HTTP Status 404
{
  "status": "invalid_group",
  "message": "User Id is not associated with a valid group."
}
HTTP Status 200
{
  "status": "invalid",
  "message": "User Id was not found."
}
HTTP Status 404
{
  "status": "disabled",
  "message": "Account is disabled."
}
HTTP Status 200
{
  "status": "lock_out",
  "message": "Account is locked out."
}
HTTP Status 200
{
  "status": "password_expired",
  "message": "Password is expired."
}
HTTP Status 200
See Server Error information below

/auth Endpoint

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/auth

For example: https://secureauth.company.com/secureauth2/api/v1/auth

The /auth POST endpoint enables SecureAuth IdP to validate information, such as username and password, and to generate OTPs for authentication.

Replace the <CONTENT> with the actual JSON Parameter values before sending the POST requests

  • <USERNAME>: User ID, e.g. jbeam
  • <PASSWORD>: User password, e.g. P@$SW0RD
  • <ANSWER>: User answer to knowledge-based question
  • <KBQ PROPERTY>: Indexed location of the specific KBQ being used for the authentication, e.g. KBQ2
  • <OTP>: One-time password generated by the OATH token
  • <DEVICE IDENTIFIER>: Unique identifier provided to SecureAuth IdP by the mobile device during the provisioning process (for OATH and Push)
  • <PIN NUMBER>: User's static PIN number (e.g. 1234)
  • <PHONE PROPERTY>: SecureAuth IdP Profile Property that is mapped to the directory field containing the required phone number, e.g. Phone1
  • <EMAIL PROPERTY>: SecureAuth IdP Profile Property that is mapped the directory field containing the required email address, e.g. Email1
  • <HELPDESK PROPERTY>: Help desk option being used for this authentication, e.g. HelpDesk1
    • In the Registration Methods tab in the SecureAuth IdP Web Admin, there are two Help Desk authentication options to enable (HelpDesk1 and HelpDesk2)
  • <IP ADDRESS>: IP Address of the user's device
  • <COMPANY>: Company name, configured in the Registration Methods tab of the Web Admin for Push-to-Accept or can be overridden in code
  • <APP>: Application / realm name, configured in the Registration Methods tab of the Web Admin for Push-to-Accept or can be overridden in code
FunctionJSON ParametersSuccess ResponseFail / Error Response

user_id

Validate user ID

{
    "user_id": "<USERNAME>",
    "type": "user_id"
}

Example:

{
    "user_id": "jbeam",
    "type": "user_id"
}
{
"status": "found",
"message": "User Id found",
}
See Fail / Error Responses in /users endpoint table

password

Validate user password

{
    "user_id": "<USERNAME>",
    "type": "password",
    "token": "<PASSWORD>"
}

Example:

{
    "user_id": "jbeam",
    "type": "password",
    "token": "P@$SW0RD"
}
{
"status": "valid",
"message": ""
}
{
"status": "invalid",
"message": "User Id or password is invalid."
}
{
"status": "invalid",
"message": "A <X> value is required for this type."
}
{
"status": "invalid",
"message": "Unknown value. Supported values are: <X>."
}

kba

Validate knowledge-based answer

{
    "user_id": "<USERNAME>",
    "type": "kba",
    "token": "<ANSWER>",
    "factor_id": "<KBQ PROPERTY>"
}

Example:

{
    "user_id": "jbeam",
    "type": "kba",
    "token": "biking",
    "factor_id": "KBQ2"
}
{
"status": "valid",
"message": ""
}
{
"status": "invalid",
"message": "Knowledge base answer is incorrect."
}
{
"status": "invalid",
"message": "KBQ Id is out of range."
}
{
"status": "invalid",
"message": "A <X> value is required for this type."
}
{
"status": "invalid",
"message": "Unknown value. Supported values are: <X>."
}

oath

Validate OATH token

{
    "user_id": "<USERNAME>",
    "type": "oath",
    "token": "<OTP>",
    "factor_id": "<DEVICE IDENTIFIER>"
}

Example:

{
    "user_id": "jbeam",
    "type": "oath",
    "token": "123456",
    "factor_id": "a0b1cd23e4f5g67h8ij90k"
}
{
"status": "valid",
"message": ""
}
 
 
{
"status": "invalid",
"message": "OTP is invalid."
}
{
"status": "invalid",
"message": "A <X> value is required for this type."
}
{
"status": "invalid",
"message": "Unknown value. Supported values are: <X>."
}

pin

Validate static PIN

   
{
    "user_id": "<USERNAME>", 
    "type" : "pin", 
    "token": "<PIN NUMBER>"
}

Example:

{
"user_id": "jbeam",
"type" : "pin",
"token": "1234"
}
   
{
"status": "valid",
"message": ""
}
   
{
"status": "invalid",
"message": "PIN is invalid."
}
{
"status": "invalid",
"message": "Request validation failed with: <X> was not present."
}

call

Deliver OTP via phone call

{
    "user_id": "<USERNAME>",
    "type": "call",
    "factor_id": "<PHONE PROPERTY>"
}

Example:

{
    "user_id": "jbeam",
    "type": "call",
    "factor_id": "Phone1"
}
{
"status": "valid",
"message": "",
"user_id": "jbeam",
"otp": "8430"
}
{
"status": "invalid",
"message": "Request validation failed with: Unknown factor id '<X>'"
}

See Server Error information below

sms

Deliver OTP via text message

{
    "user_id": "<USERNAME>",
    "type": "sms",
    "factor_id": "<PHONE PROPERTY>"
}

Example:

{
    "user_id": "jbeam",
    "type": "sms",
    "factor_id": "Phone1"
}
{
"status": "valid",
"message": "",
"user_id": "jbeam",
"otp": "8430"
}

email

Deliver OTP via email

{
    "user_id": "<USERNAME>",
    "type": "email",
    "factor_id": "<EMAIL PROPERTY>"
}

Example:

{
    "user_id": "jbeam",
    "type": "email",
    "factor_id": "Email1"
}
{
"status": "valid",
"message": "",
"user_id": "jbeam",
"otp": "8430"
}

push

Deliver OTP via Push Notification

{
    "user_id": "<USERNAME>",
    "type": "push",
    "factor_id": "<DEVICE IDENTIFIER>"
}

Example:

{
    "user_id": "jbeam",
    "type": "push",
    "factor_id": "z0y9x87wv6u5t43srq2p1on"
}
{
"status": "valid",
"message": "",
"user_id": "jbeam",
"otp": "8430"
}

push_accept

Deliver Push-to-Accept notification

{
    "user_id" : "<USERNAME>",
    "factor_id" : "<DEVICE IDENTIFIER>",
    "type" : "push_accept",
    "push_accept_details" : {
        "company_name" : "<COMPANY>",
        "application_description" : "<APP>",
        "enduser_ip" : "<IP ADDRESS>"
    }
}

Example:

{
"user_id" : "jbeam",
"factor_id" : "8117b62897734d71b4XXXXX",
"type" : "push_accept",
"push_accept_details" : {
"company_name" : "ACME Corp",
"application_description" : "Salesforce",
"enduser_ip" : "111.222.33.44"
}
}
{
"reference_id": "a7e855c1-45a3-XXXXXX",
"status": "valid",
"message": "",
"user_id": "jbeam"
}

help_desk

Deliver OTP via help desk

{
    "user_id": "<USERNAME>",
    "type": "help_desk",
    "factor_id": "<HELPDESK PROPERTY>"
}

Example:

{
    "user_id": "jbeam",
    "type": "help_desk",
    "factor_id": "HelpDesk1"
}
{
"status": "valid",
"message": "",
"user_id": "jbeam",
"otp": "8430"
}
/auth/REF ID Endpoint

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/auth/<REF ID>

For example: https://secureauth.company.com/secureauth2/api/v1/auth/f50ab2d7-178f-4421-b3ae-9f5634fa54ef

The /auth/<REF ID> GET endpoint is used to check the status of Push-to-Accept responses. When a Push-to-Accept request is made, the corresponding response contains a Reference ID, which is then appended to the /auth endpoint to continuously check whether the login request is accepted, denied, pending, or other.

Definitions

status: The status of Push-to-Accept response (found, not_found, or invalid); will always be in response

message: Additional information regarding the status; will always be in response

Success ResponseFail / Error Response
{
"status": "found",
"message": "ACCEPTED"
}
{
"status": "not_found",
"message": "NOTFOUND"
}
{
"status": "found",
"message": "DENIED"
}
{
"status": "invalid",
"message": "Invalid reference ID."
}
{
"status": "found",
"message": "FAILED"
}
{
"status": "found",
"message": "EXPIRED"
}
{
"status": "found",
"message": "PENDING"
}

/adaptauth Endpoint

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/adaptauth

For example: https://secureauth.company.com/secureauth2/api/v1/adaptauth

The /adaptauth POST endpoint enables SecureAuth IdP Adaptive Authentication, which analyzes an end-user's profile, group, IP address, country, geo-velocity, and any risks detected by threat intelligence data.

The API utilizes the information configured in the Adaptive Authentication section of the SecureAuth IdP Web Admin. Refer to Adaptive Authentication Configuration Guide (version 8.2) for more information.

SecureAuth IdP returns a response that contains the Status, Realm Workflow, and Suggested Action. The Status is the configured Failure Action; the Realm Workflow is the workflow configured in the Web Admin; and the Suggested Action is the suggested next step to take based on the configurations.

StatusDescription
ContinueEnd-user continues onto the configured workflow (Failure Action: Resume auth in Web Admin)
SkipTwoFactorEnd-user bypasses 2-Factor Authentication and moves forward to next workflow step, e.g. password (Failure Action: Step down auth in Web Admin)
TwoFactorEnd-user undergoes additional 2-Factor Authentication (Failure Action: Step up auth in Web Admin)
AuthenticatedEnd-user is taken directly to post-authentication target, bypassing additional analysis or 2-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 ActionDescription
2ndfactor_passwordEnd-user must undergo 2-Factor Authentication and then provide password
passwordEnd-user must provide password
2ndfactorEnd-user must undergo 2-Factor Authentication
noneEnd-user is not required to perform authentication or password validation
stopEnd-user is stopped immediately in workflow and cannot continue
redirectEnd-user is redirected to the provided URL
JSON ParametersSuccess ResponseFailure / Error Response
ContinueSkipTwoFactorTwoFactorAuthenticatedHardStopRedirect
{
    "user_id" : "<USERNAME>",
    "parameters" : {
        "ip_address" : "<IP ADDRESS>"
        }
}

Example:

{
"user_id" : "jbeam",
"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 Endpoint

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/accesshistory

For example: https://secureauth.company.com/secureauth2/api/v1/accesshistory

The /accesshistory POST endpoint enables SecureAuth IdP to create a history of end-user's logins for use in geo-velocity (Adaptive Authentication). Once an end-user is authenticated, the information is posted to the /accesshistory endpoint, and a new entry is created and stored in the user profile. For the next login attempt, SecureAuth IdP can use the stored information to validate whether the distance traveled from the previous login to the current attempt is feasible.

If geo-velocity is not enabled for Adaptive Authentication (in the SecureAuth IdP Web Admin), then this endpoint is not necessary.

JSON ParametersSuccess ResponseFailure / Error Response
{
    "user_id" : "<USERNAME>",
    "ip_address" : "<IP ADDRESS>"
} 

Example:

{
"user_id" : "jbeam",
"ip_address" : "111.222.33.44"
{
"status": "valid",
"message": "Access History request has been processed."
}
{
"status": "invalid",
"message": "Access History was not saved."
}

/ipeval Endpoint

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/ipeval

For example: https://secureauth.company.com/secureauth2/api/v1/ipeval

The /ipeval POST endpoint enables SecureAuth IdP to evaluate the IP Address for risk factors based on threat intelligence data. This endpoint can be used as a standalone feature rather than alongside the other Adaptive Authentication features used in the /adaptauth endpoint.

If using the /ipeval endpoint and not the /adaptauth endpoint, then no configuration is required in the Adaptive Authentication section of the SecureAuth IdP Web Admin.

FunctionJSON ParametersSuccess ResponseFailure / Error Response

risk

IP Address Risk Evaluation

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

Example:

{
    "user_id": "jbeam",
    "type": "risk",
    "ip_address": "11.222.33.44"
} 
{
"ip_evaluation": {
"method": "aggregation",
"ip": "5.2.189.251",
"risk_factor": 99,
"risk_color": "red",
"risk_desc": "Extreme risk involved",
"geoloc": {
"country": "Romania",
"country_code": "RO",
"region": "Iasi",
"region_code": "Iasi",
"city": "Iasi",
"latitude": "47.16667",
"longtitude": "27.6",
"internet_service_provider": "RCS & RDS Business",
"organization": "rdsnet.ro"
},
"factoring": {
"threatType": 99,
"threatCategory": 5
}
},
"status": "verified",
"message": ""
}
{
"status": "invalid",
"message": "Service is offline. IP could not be evaluated at this time."
}

This response may occur because the SecureAuth IdP appliance does not have the required license for this feature

Contact SecureAuth Support to upgrade

{
"status": "invalid",
"message": "Unknown value. Supported values are: risk."
}
{
"status": "invalid",
"message": "<X> was not present in request."
}
{
"status": "invalid",
"message": "Request validation failed with: Invalid IP address."
}
See Server Error information below

Risk Factor (threatType) Scores

Threat Type (AE.IP.threatType)ScoreSecureAuth IdP Risk CategoryDefinition
Anonymous Proxy100ExtremeAuthentication is coming from a server that is designed to hide or anonymize the actual source IP Address
Attacker99ExtremeIndicators confirmed to host malicious content, has functioned as a command-and-control (C2) server, and / or has otherwise acted as a source of malicious activity
Compromised98ExtremeIndicators confirmed to host malicious content due to compromise or abuse – the exact time and length of compromise is unknown unless disclosed within the report
Related88HighIndicators likely related to an attack, but potentially only partially confirmed – detailed by one or more methods, like passive DNS, geo-location, and connectivity detection
Victim89HighIndicators representing an entity that has been confirmed to have been victimized by malicious activity, where actors have attempted or succeeded compromise
Uncategorized80HighUncategorized threat

threatCategory Scores

Threat Category (AE.IP.threatCategory)Response ValueDefinition
Anonymous Proxy0Authentication is coming from a server that is designed to hide of anonymize the actual source IP Address
Cyber Espionage1Global issue with highly sophisticated nation-states and other actors targeting military, political, and commercial interests to gain decision advantage
Hacktivism2Activity ranges from nuisance level to sophisticated campaigns conducted by globally coordinated actors using increasingly sophisticated tools to negatively impact revenue or damage the brand
Enterprise3Threats specifically targeted at Enterprise
Critical Infrastructure4Threats specifically targeted at Critical Infrastructure
Cyber Crime5Threats typically orchestrated by criminal elements for financial benefit
Vulnerability and Exploitation6Threats targeting known software vulnerabilities

/dfp Endpoints

The /dfp endpoints enable the use of SecureAuth IdP's device / browser fingerprinting, which collects unique information from an end-user's device or browser, and stores it as a "fingerprint" in the user profile. This fingerprint is then used as a comparison for future login attempts; and if a match is made, then it is used as the second factor of authentication.

To utilize these endpoints, the SecureAuth IdP realm must be configured for Device / Browser Fingerprinting. Refer to Device / Browser Fingerprinting - Heuristic-based Authentication for more information.

/dfp/js Endpoint

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/dfp/js

For example: https://secureauth.company.com/secureauth2/api/v1/dfp/js

The /dfp/js GET endpoint enables the application to retrieve the javascript reference that is required to generate fingerprints. Using the reference, end-users' devices / browsers are analyzed and most of the required information is collected; but the remaining characteristics must be provided by the application.

Response to request:

{
    "src": "https://SecureAuthIdPFQDN/SecureAuthIdPRealm/assets/scripts/api/secureauth-api.js?ver=8.1.1.071"
}

HTML Javascript Usage Example

This is an example of how to use the javascript reference to capture a client-side digital fingerprint.

<script src="https://company.secureauth.com/SecureAuth2/assets/scripts/api/secureauth-api.js?ver=8.1.1.071"></script>
<script>
    $(function() {
        // invoke getFingerprint() method to capture
        // client-side info and serialize to JSON string.
        var serializedData = JSON.stringify(secureAuth.api.getFingerprint());                
        
        // assign JSON string to an input for posting
        // to web server.
        $('#results').val(serializedData);
    });
</script>

Fingerprint Components

Provided by Javascript ReferenceProvided by Application
fontshost_address (IP Address of end-user client)
pluginsuser_id
timezoneaccept
videoaccept_charset
local_storageaccept_encoding
session_storageaccept_language


ie_user_data
cookie_enabled
user_agent
/dfp/validate Endpoint

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/dfp/validate

For example: https://secureauth.company.com/secureauth2/api/v1/dfp/validate

The /dfp/validate POST endpoint compares the presented fingerprint with those stored in the user profile. Based on the information provided and that from the directory, SecureAuth IdP returns a response stating whether the fingerprint is found or not found. If the fingerprint is found, then the end-user has completed 2-Factor Authentication, and no additional authentication steps are required for identity validation.

Definitions

  • fingerprint_id: GUID of the fingerprint
  • fingerprint_name: Descriptive name derived from the user_agent string
  • score: Match score of the provided fingerprint (out of 100.00)
  • match_score: Minimum score allowed to be accepted as second factor authentication (configured in realm)
  • update_score: Minimum score allowed to be accepted to update existing fingerprint with new information (configured in realm, requires 2-Factor Authentication for update)
  • status: Status of the matching outcomes:
    • found: Fingerprint found with acceptable match_score
    • found_for_update: Fingerprint found with unacceptable match_score, but acceptable update_score and can be updated by posting to /dfp/confirm endpoint
    • found_with_id_mismatch: Fingerprint found, but with different Fingerprint ID
    • not_found: Fingerprint not found and new one must be created by posting to /dfp/confirm endpoint
  • message: Additional information regarding the status
FunctionJSON ParametersResponse
Validate NEW Fingerprint
{
    "user_id" : "<USERNAME>",
    "host_address" : "<IP ADDRESS>",
    "fingerprint" : {
        "fonts" : "<FONT LIST>",
        "plugins" : "<PLUGIN LIST>",
        "timezone" : "<TIMEZONE>",
        "video" : "<VIDEO>",
        "local_storage" : "<T OR F>",
        "session_storage" : "<T OR F>",
        "ie_user_data" : "<T OR F>",
        "cookie_enabled" : "<T OR F>",
        "user_agent": "<USER AGENT INFO>",
        "accept" : "<ACCEPT INFO>",
        "accept_charset" : "<CHARSET INFO>",
        "accept_encoding" : "<ENCODING INFO>",
        "accept_language" : "<LANG INFO>"
    }
}

Example:

{
"user_id" : "jbeam",
"host_address" : "111.222.33.44",
"fingerprint" : {
"fonts" : "Agency FB,Aharoni,Algerian,Andalus,Angsana New,AngsanaUPC ...",
"plugins" : "ActiveTouch General Plugin Container:ActiveTouch General Plugin Container Version 105 ...",
"timezone" : "America/Los_Angeles",
"video" : "1920x1080x24",
"local_storage" : "false",
"session_storage" : "false",
"ie_user_data" : "false",
"cookie_enabled" : "true",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:41.0) Gecko/20100101 Firefox/41.0",
"accept" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"accept_charset" : "",
"accept_encoding" : "gzip, deflate",
"accept_language" : "en-US,en;q=0.5"
}
}

Refer to the table in the /dfp/js endpoint section for more information on the required fingerprint components

{
"fingerprint_id": "58f0f98642fe4354ba65a35a0d8bc6ff",
"fingerprint_name": "Windows 7 - Firefox 41.0",
"score": "0.00",
"match_score": "95.00",
"update_score": "80.00",
"status": "not_found",
"message": ""
}
Validate KNOWN Fingerprint  
{
    "user_id" : "<USERNAME>",
    "host_address" : "<IP ADDRESS>",
    "fingerprint_id" : "<FP ID>",
    "fingerprint" : {
        "fonts" : "<FONT LIST>",
        "plugins" : "<PLUGIN LIST>",
        "timezone" : "<TIMEZONE>",
        "video" : "<VIDEO>",
        "local_storage" : "<T OR F>",
        "session_storage" : "<T OR F>",
        "ie_user_data" : "<T OR F>",
        "cookie_enabled" : "<T OR F>",
        "user_agent": "<USER AGENT INFO>",
        "accept" : "<ACCEPT INFO>",
        "accept_charset" : "<CHARSET INFO>",
        "accept_encoding" : "<ENCODING INFO>",
        "accept_language" : "<LANG INFO>"
    }
}

Example:

{
"user_id" : "jbeam",
"host_address" : "111.222.33.44",
"fingerprint_id": "58f0f98642fe4354ba65a35a0d8bc6ff",
"fingerprint" : {
"fonts" : "Agency FB,Aharoni,Algerian,Andalus,Angsana New,AngsanaUPC ...",
"plugins" : "ActiveTouch General Plugin Container:ActiveTouch General Plugin Container Version 105 ...",
"timezone" : "America/Los_Angeles",
"video" : "1920x1080x24",
"local_storage" : "false",
"session_storage" : "false",
"ie_user_data" : "false",
"cookie_enabled" : "true",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:41.0) Gecko/20100101 Firefox/41.0",
"accept" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"accept_charset" : "",
"accept_encoding" : "gzip, deflate",
"accept_language" : "en-US,en;q=0.5"
}
}
{
"fingerprint_id": "58f0f98642fe4354ba65a35a0d8bc6ff",
"fingerprint_name": "Windows 7 - Firefox 41.0",
"score": "100.00",
"match_score": "95.00",
"update_score": "80.00",
"status": "found",
"message": ""
}
{
"fingerprint_id": "58f0f98642fe4354ba65a35a0d8bc6ff",
"fingerprint_name": "Windows 7 - Firefox 41.0",
"score": "90.00",
"match_score": "95.00",
"update_score": "80.00",
"status": "found_for_update",
"message": ""
}
{
"fingerprint_id": "a31332450f284e9bbb1572e7c1c4927a",
"fingerprint_name": "Windows 7 - Firefox 41.0",
"score": "100.00",
"match_score": "95.00",
"update_score": "80.00",
"status": "found_with_id_mismatch",
"message": ""
}
/dfp/confirm Endpoint

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/dfp/confirm

For example: https://secureauth.company.com/secureauth2/api/v1/dfp/confirm

The /dfp/confirm POST endpoint stores the new or updated fingerprints in the user profile in the directory. If a fingerprint posted to the /dfp/validate endpoint returns a not_found or found_for_update status, then the information must be posted to the /dfp/confirm endpoint to create / update the fingerprint.

Once the fingerprint is validated, SecureAuth IdP returns a fingerprint_id, which is then posted to the confirm endpoint to create the entry.

JSON ParametersSuccess ResponseFailure / Error Response
{
    "user_id" : "<USERNAME>",
    "fingerprint_id" : "<FP ID>"
}

Example:

{
"user_id" : "jbeam",
"fingerprint_id" : "58f0f98642fe4354ba65a35a0d8bc6ff"
}
 
{
"fingerprint_id": "58f0f98642fe4354ba65a35a0d8bc6ff",
"fingerprint_name": "Windows 7 - Firefox 41.0",
"status": "verified",
"message": "Fingerprint has been confirmed.",
"user_id": "jbeam"
}
{
"fingerprint_id": "58f0f98642fe4354ba65a35a0d8bc6ff",
"status": "not_found",
"message": "Could not resolve fingerprint with ID '38ffeef7e10047418f779357'.",
"user_id": "jbeam"
}
 
{
"fingerprint_id": "58f0f98642fe4354ba65a35a0d8bc6ff",
"fingerprint_name": "Windows Vista - Firefox 41.0",
"status": "found",
"message": "Fingerprint exists.",
"user_id": "jbeam"
}

If a server error is encountered, then the follow response is returned:

{
  "status": "server_error",
  "message": "<Exception message describing the issue.>",
}
HTTP Status 500