Documentation

Introduction

Use this guide to configure the SecureAuth Authentication API to evaluate an IP address for risk factors based on threat intelligence data. The Authentication API configured to evaluate an IP address can be utilized as a standalone feature or alongside the other Adaptive Authentication features.

Prerequisites

1. (OPTIONAL) Have special SecureAuth IdP license to utilize IP Reputation / Threat Data analysis function

Contact SecureAuth Support for more information or to upgrade

2. Complete the steps in the Authentication API Guide

3. (OPTIONAL) If Adaptive Authentication is used, then complete the Adaptive Authentication configuration steps in the SecureAuth IdP Web Admin

4. If Adaptive Authentication is configured and only the /ipeval endpoint is used – and not the /adaptauth endpoint – then no configuration is required in the Adaptive Authentication section of the SecureAuth IdP Web Admin

Endpoint

The /ipeval endpoint uses the POST method to evaluate an IP address for risk factors based on threat intelligence data

This endpoint can be utilized as a standalone feature rather than alongside the other Adaptive Authentication features used in the /adaptauth endpoint – refer to the Adaptive Authentication API Guide for endpoint configuration information

POST
HTTP MethodURIExample
POST/api/v1/ipeval
https://secureauth.company.com/secureauth2/api/v1/ipeval
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
Definitions
  • user_id: End-user ID provided
  • type: Threat type
  • ip_address: End-user IP address
  • method: Factors used to determine the risk score
  • risk_factor: Threat type score
  • status: State of the user IP address
  • message: Reason for status
POST Endpoint JSON Parameters and Response Examples
JSON ParametersSuccess ResponseFailure / Error Response
{
    "user_id": "<USERNAME>",
    "type": "risk",
    "ip_address": "<IP ADDRESS>"
} 

Example:

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

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

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