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, Adaptive Authentication, and Behavioral Biometric profile; 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 Multi-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 9.0.x
Information about using Identity Management API tools can be found in the Identity Management API Guide
If using SecureAuth IdP v9.1, see Authentication API Guide and Profile Validation API Guide for information on how to configure SecureAuth Authentication API to validate end-user information and to generate OTPs for end-user authentication
See Authentication API: Send Ad hoc OTP without Existing User Profile for specific configuration steps when using ad hoc OTP delivery to users who are not registered in the directory
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 Multi-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
The Behavioral Biometrics feature only supports LDAP directory integrations, while other Authentication API features support most directory type integrations
Ensure that the Registration Methods Profile Properties (e.g. Phone 1, Email 1, etc.) are accurately mapped to directory attributes to enable Multi-Factor Authentication workflows
NOTE: Only API section steps are required; all other Web Admin steps are optional and should be performed based on the features to be implemented
1. Check Enable API for this realm in the API Key section
2. Click Generate Credentials to create a new Application ID and Application Key
The Application ID and Application Key are unique per realm
In appearance the API key looks like it is comprised of 64 random characters, but it is actually is comprised of 32 two-character base-16 hexadecimal values
This is important to note when using the API key to produce the HMAC hash
3. Click Select & Copy to copy the contents from the fields
These values will be required in the HTTP Header configuration steps below
4. Check Enable Authentication API in the API Permissions section
Click Save once the configurations have been completed and before leaving the API page to avoid losing changes
1. In the Registration Configuration section, enable at least one Multi-Factor Authentication mechanism to be utilized in the Authentication API workflow
Refer to Registration Methods Tab Configuration for more information
If not using Multi-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 the Registration Methods Profile Properties (e.g. Phone 1, Email 1, etc.) are mapped appropriately to directory attributes in the Data tab to enable Multi-Factor Authentication
Click Save once the configurations have been completed and before leaving the Registration Methods / Multi-Factor Methods page to avoid losing changes
1. In the Adaptive Authentication section, configure the realm to enable / disable functions to be used by the application
Refer to Adaptive Authentication Guide for the full configuration steps
Be sure to select the preferred Authentication Mode (in the Workflow section), as it dictates the suggested actions by the API
Click Save once the configurations have been completed and before leaving the Workflow page to avoid losing changes
2. In the IP Configuration section, set the Public IP Address to the appliance's public IP address or 127.0.0.1 as preferred
This step is required if using Geo-Velocity analysis to avoid errors with the Adaptive Authentication API
Click Save once the configurations have been completed and before leaving the System Info page to avoid losing changes
1. In the Phone Number Blocking frame in the Registration Configuration section, enable at least one option
- Block phone numbers from the following [selected] sources
- Block phone numbers that have recently ported carriers
- Block or allow phone numbers by carrier or country
Refer to Phone Number Profiling Service Configuration Guide for complete configuration steps
See /numberprofile Endpoints for API configuration information
Click Save once the configurations have been completed and before leaving the Multi-Factor Methods page to avoid losing changes
Multi-Factor Throttling requires SecureAuth IdP version 9.0.2 or greater
1. In the Multi-Factor Settings section, check Enable multi-factor throttling
2. Configure the settings to customize the number of allowed failed attempts and the length of the rolling time window
3. Configure the action to take upon exceeding the allowed failed attempts
4. Select a profile property to store the count of failed attempts
Refer to Multi-Factor Throttling Configuration Guide for the full configuration steps
Click Save once the configurations have been completed and before leaving the Multi-Factor Methods page to avoid losing changes
1. In the Membership Connection Settings section, map a directory field to the Fingerprints property
In typical AD deployments the audio directory field is utilized
2. Check Writable
The Fingerprints Property can be stored as Plain Binary or in JSON format, and has distinct requirements for the LDAP directory attribute mapped to the Property based on the Data Format selection
For Plain Binary, these requirements must be met for the directory field that contains the fingerprint information:
- Length: 4096 minimum
- Data Type: Octet string (bytes)
- Multi-valued
For JSON, these requirements must be met for the directory field that contains the fingerprint information:
- Length: No limit / undefined
- Data Type: DirectoryString
- Multi-valued
3. 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
Click Save once the configurations have been completed and before leaving the Data page to avoid losing changes
1. In the Profile Fields section, map the Behavior Biometrics Property to a directory field, e.g. comment
2. Check Writable
Click Save once the configurations have been completed and before leaving the Data page to avoid losing changes
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
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)
This step is executed by calling the HMAC and producing the hash value
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
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)
This step is executed by calling the HMAC and producing the hash value
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
When an Authorization Header cannot be validated, one of the following responses will be returned:
{ | { |
{ | { |
{ | { |
{ | { |
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
| HTTP Method | URI | Example |
|---|---|---|
| GET |
| https://secureauth.company.com/secureauth2/api/v1/users/jsmith/factors |
The /factors endpoint returns a list of enabled Multi-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 Multi-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:
| Success | Fail / Error |
|---|---|
{
"status": "found",
"message": "",
"user_id": "jsmith",
"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": "jsmith@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"
}, { | {
"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": "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 |
| HTTP Method | URI | Example |
|---|---|---|
| GET | /api/v1/users/{username}/throttle | https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle |
| PUT | /api/v1/users/{username}/throttle | https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle |
The Multi-Factor Throttling API provides protection against an attacker attempting to 1) brute force an account via trial-and-error using large numbers of OTPs and 2) disrupt service via a denial-of-service attack where an attacker attempts to overwhelm the system by generating a large number of OTPs
The GET method retrieves the current count of Multi-Factor attempts for the given username
The PUT method resets the count of Multi-Factor attempts to 0 (suggested after a successful authentication); the attempt count is stored in a directory attribute configured in the Web Admin (refer to Multi-Factor Throttling Configuration Guide for more information)
The thresholds for this API are configured within the Multi-Factor Methods tab of the Web Admin; any authentication attempts exceeding these thresholds are disregarded and an error message is displayed to the end-user
| GET Responses: | PUT Responses: | ||
| Success | Failure | Success | Failure |
|---|---|---|---|
{HTTP Status 200 | {HTTP Status 404 | {HTTP Status 200 | {HTTP Status 404 |
NOTE: The SecureAuth IdP Detect license is required to use this feature / endpoint
| HTTP Method | URI | Example |
|---|---|---|
| POST / PUT | /api/v1/numberprofile | https://secureauth.company.com/secureauth2/api/v1/numberprofile |
Endpoints for /numberprofile are used on demand to view an end-user's phone number profile and update the record if information such as carrier, network, and / or country has changed
NOTE: For phone numbers that are roaming, SecureAuth IdP still retrieves the carrier information, upholding the carrier blocking configurations set in the Web Admin
The POST method retrieves the phone profile record from the data provider which includes the original carrier information
If a change needs to be made to the end-user carrier information, the PUT method is used to update the directory to reflect the change – e.g. recently-ported phone number status change and / or carrier change
After the change is made, a subsequent POST call retrieves the original carrier information from the directory and the current carrier information from the data provider
If a discrepancy exists between the original carrier information and current carrier information, a PUT call is made to update the phone profile record
Definitions
user_id: user ID provided
phone_number: user phone number provided
status: state of the user ID or phone number provided (not_found, invalid, valid, etc.)
message: additional information regarding the status of the user ID or phone number; will always be in response
providerRequestId: unique reference identification number for the request, generated by the data provider
portedStatus: user phone status for the option to block phone numbers that recently changed carriers (not_ported, ported)
originalCarrier: the first time a POST call is made, user phone profile information from the data provider information appears here – on subsequent POST calls, user phone profile information stored in the directory appears here
currentCarrier: following a PUT call and a subsequent POST call, user phone profile information from the data provider appears here
carrierCode: 6-digit number or a concatenation of the country code and phone type
carrier: name of the carrier or a concatenation of the country code and phone type
countryCode: 2-character country code
networkType: phone connection source (landline, tollfree, mobile, virtual, unknown, landline_tollfree)
carrierStatus:
status: state of the carrier (blocked, allowed) based on the configuration defined in the Web Admin
reason: explanation for the state of the carrier (network_type, ported, country, carrier) based on the configuration defined in the Web Admin
See Phone Number Profiling Service for configuration settings
| JSON Parameters | Success Response (Phone profile is returned with this response) | Fail / Error Response (Phone profile is not returned with this response) |
|---|---|---|
{
"user_id": "<USERNAME>",
"phone_number": "<PHONE NO.>"
}
Example: {
"user_id": "jsmith",
"phone_number": "19491234567"
} | {} | {HTTP Status 200 (OK - Non-existing user) |
{HTTP Status 404 (Not Found - Non-existing endpoint) | ||
{HTTP Status 400 (Bad Request - Missing phone number) | ||
{HTTP Status 200 (OK - Invalid phone number) | ||
{HTTP Status 404 (Not Found - Non-existing endpoint) |
| JSON Parameters | Success Response (Phone profile is returned with this response) | Fail / Error Response (Phone profile is not returned with this response) |
|---|---|---|
{
"user_id": "<USERNAME>",
"phone_number": "<PHONE NO.>",
"portedStatus": "not_ported",
"carrierInfo": {
"carrierCode": "<6-DIGIT NO. OR COUNTRY CODE + PHONE TYPE>",
"carrier": "<CARRIER NAME OR COUNTRY CODE + PHONE TYPE",
"countryCode": "<2-CHARACTER COUNTRY CODE>",
"networkType": "<TYPE OF NETWORK CONNECTION>"
}
}
Example: {
"user_id": "jsmith",
"phone_number": "19491234567",
"portedStatus":"not_ported",
"carrierInfo": {
"carrierCode": "US-FIXED",
"carrier": "T-mobile USA, Inc.",
"countryCode": "US",
"networkType": "mobile"} } | {HTTP Status 200 (OK - Successful PUT) | {HTTP Status 200 (OK - Non-existing user) |
{HTTP Status 404 (Not Found - Non-existing endpoint) | ||
{HTTP Status 400 (Bad Request - Missing phone number) | ||
{HTTP Status 200 (OK - Invalid phone number) | ||
{HTTP Status 404 (Not Found - Non-existing endpoint) |
| HTTP Method | URI | Example |
|---|---|---|
| POST | /api/v1/auth | https://secureauth.company.com/secureauth2/api/v1/auth |
Validates auth information (e.g. username, password, etc.) and generates OTPs for authentication
Definitions
evaluate_number: (optional) evaluate recipient's phone number and return whether the number is valid to be used for the dispatch of an SMS or Voice OTP
Replace the <CONTENT> with the actual JSON Parameter values before sending the POST requests
<USERNAME>: User ID, e.g. jsmith
<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 or on an ad hoc basis
<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
<UNREGISTERED PHONE>: Phone number that is not stored in the directory
<UNREGISTERED EMAIL>: Email address that is not stored in the directory
<HELPDESK PROPERTY>: Help desk option being used for this authentication, e.g. HelpDesk1
In the Registration Methods / Multi-Factor 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 / Multi-Factor 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 / Multi-Factor Methods tab of the Web Admin for Push-to-Accept or can be overridden in code
Evaluate Phone Number for OTP
Include the optional evaluate_number flag in any /auth request to evaluate a recipient's phone number for validity before delivering an OTP via SMS or Voice call. The criteria used to determine whether a phone number is valid or invalid for use is configured in the Multi-Factor Methods tab.
Refer to Phone Number Profiling Service Configuration Guide for more information
NOTE: For phone numbers that are roaming, SecureAuth IdP still retrieves the carrier information, upholding the carrier blocking configurations set in the Web Admin
For OTP delivery, SecureAuth IdP delivers to the OTP to the carrier, and then the carrier forwards the message to the roaming partner's network
Send Ad hoc OTP
The Send Ad hoc OTP API allows for an OTP to be dispatched on an ad hoc basis to a valid phone number or email address that is not currently stored in the directory (i.e. unregistered)
Use the token request parameter to define unregistered recipient phone numbers and email addresses
Refer to Authentication API: Send Ad hoc OTP without Existing User Profile for specific configuration steps when using ad hoc OTP delivery to users that are not registered in the directory
| Function | JSON Parameters | Success Response | Fail / Error Responses |
|---|---|---|---|
ad hoc call Deliver OTP via phone call to a phone number not stored in the directory | {
"user_id": "<USERNAME>",
"type": "call",
"token": "<UNREGISTERED PHONE>",
"evaluate_number": "true"
}
Example: {"evaluate_number": "true" } | {"status": "valid", | {
"status": "invalid",
"message": "Request validation failed with: User Id was not present."
}{{
Note that for ad hoc OTP delivery the only supported " {{See Server Error information below |
ad hoc sms Deliver OTP via text message to a phone number not stored in the directory | {
"user_id": "<USERNAME>",
"type": "sms",
"token": "<UNREGISTERED PHONE>"
"evaluate_number": "true"
}
Example: {"evaluate_number": "true" } | {"status": "valid", | |
ad hoc email Deliver OTP via email to an email address not stored in the directory | {
"user_id": "<USERNAME>",
"type": "email",
"token": "<UNREGISTERED EMAIL>"
}
Example: { | {"status": "valid", |
| Function | JSON Parameters | Success Response | Fail / Error Response |
|---|---|---|---|
user_id Validate user ID | {
"user_id": "<USERNAME>",
"type": "user_id"
}
Example: {
"user_id": "jsmith",
"type": "user_id"
} | { | See Fail / Error Responses in /users endpoint table |
password Validate user password | {
"user_id": "<USERNAME>",
"type": "password",
"token": "<PASSWORD>"
}
Example: {
"user_id": "jsmith",
"type": "password",
"token": "P@$SW0RD"
} | { | { |
{ | |||
{ | |||
kba Validate knowledge-based answer | {
"user_id": "<USERNAME>",
"type": "kba",
"token": "<ANSWER>",
"factor_id": "<KBQ PROPERTY>"
}
Example: {
"user_id": "jsmith",
"type": "kba",
"token": "biking",
"factor_id": "KBQ2"
} | { | { |
{ | |||
{ | |||
{ | |||
oath Validate OATH token | {
"user_id": "<USERNAME>",
"type": "oath",
"token": "<OTP>",
"factor_id": "<DEVICE IDENTIFIER>"
}
Example: {
"user_id": "jsmith",
"type": "oath",
"token": "123456",
"factor_id": "a0b1cd23e4f5g67h8ij90k"
} | { | { |
{ | |||
{ | |||
pin Validate static PIN | {
"user_id": "<USERNAME>",
"type" : "pin",
"token": "<PIN NUMBER>"
}
Example: { | { | { |
{ | |||
call Deliver OTP via phone call | {
"user_id": "<USERNAME>",
"type": "call",
"factor_id": "<PHONE PROPERTY>",
"evaluate_number": "true"
}
Example: {
"user_id": "jsmith",
"type": "call",
"factor_id": "Phone1" | { | {See Server Error information below |
sms Deliver OTP via text message | {
"user_id": "<USERNAME>",
"type": "sms",
"factor_id": "<PHONE PROPERTY>"
"evaluate_number": "true"
}
Example: {
"user_id": "jsmith",
"type": "sms",
"factor_id": "Phone1""evaluate_number": "true" } | { | |
Deliver OTP via email | {
"user_id": "<USERNAME>",
"type": "email",
"factor_id": "<EMAIL PROPERTY>"
}
Example: {
"user_id": "jsmith",
"type": "email",
"factor_id": "Email1"
} | { | |
push Deliver OTP via Push Notification | {
"user_id": "<USERNAME>",
"type": "push",
"factor_id": "<DEVICE IDENTIFIER>"
}
Example: {
"user_id": "jsmith",
"type": "push",
"factor_id": "z0y9x87wv6u5t43srq2p1on"
} | { | |
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: { | { | |
help_desk Deliver OTP via help desk | {
"user_id": "<USERNAME>",
"type": "help_desk",
"factor_id": "<HELPDESK PROPERTY>"
}
Example: {
"user_id": "jsmith",
"type": "help_desk",
"factor_id": "HelpDesk1"
} | { |
| HTTP Method | URI | Example |
|---|---|---|
| GET | /api/v1/auth/{REF_ID} | https://secureauth.company.com/secureauth2/api/v1/auth/f50ab2d7-178f-4421-b3ae-9f5634fa54ef |
Checks 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 Response | Fail / Error Response |
|---|---|
{ | { |
{ | { |
{ | |
{ | |
{ |
| HTTP Method | URI | Example |
|---|---|---|
| POST | /api/v1/adaptauth | https://secureauth.company.com/secureauth2/api/v1/adaptauth |
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 Guide 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
| Status | Description |
|---|---|
| Continue | End-user continues onto the configured workflow (Failure Action: Resume auth in Web Admin) |
| SkipTwoFactor | End-user bypasses 2-Factor Authentication and moves forward to next workflow step, e.g. password (Failure Action: Step down auth in Web Admin) |
| TwoFactor | End-user undergoes additional 2-Factor Authentication (Failure Action: Step up auth in Web Admin) |
| Authenticated | End-user is taken directly to post-authentication target, bypassing additional analysis or 2-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, e.g. another SecureAuth IdP realm (Failure Action: Redirect in Web Admin) |
| Suggested Action | Description |
| 2ndfactor_password | End-user must undergo 2-Factor Authentication and then provide password |
| password | End-user must provide password |
| 2ndfactor | End-user must undergo 2-Factor Authentication |
| none | End-user is not required to perform authentication or password validation |
| stop | End-user is stopped immediately in workflow and cannot continue |
| 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: {
The IP Address is not required if only performing user / group restriction; otherwise, it is required for all other functionality | { | { | { | { | { | { | { |
{ | { | { | { | { | { | ||
{ | { | { | { | { | { | ||
{ | { | { | { | { | { | ||
{ | { | { | { | { | { | ||
{ | { | { | { | { | { | ||
{ | { | { | { | { | { | ||
| HTTP Method | URI | Example |
|---|---|---|
| POST | /api/v1/accesshistory | https://secureauth.company.com/secureauth2/api/v1/accesshistory |
Creates 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 Parameters | Success Response | Failure / Error Response |
|---|---|---|
{
"user_id": "<USERNAME>",
"ip_address": "<IP ADDRESS>"
}
Example: { | { | { |
| HTTP Method | URI | Example |
|---|---|---|
| POST | /api/v1/ipeval | https://secureauth.company.com/secureauth2/api/v1/ipeval |
Evaluates an 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.
| Function | JSON Parameters | Success Response | Failure / Error Response |
|---|---|---|---|
risk IP Address Risk Evaluation | {
"user_id": "<USERNAME>",
"type": "risk",
"ip_address": "<IP ADDRESS>"
}
Example: {
"user_id": "jsmith",
"type": "risk",
"ip_address": "11.222.33.44"
} | { | {
This response may occur because the SecureAuth IdP appliance does not have the required license for this feature Contact SecureAuth Support to upgrade |
{ | |||
{ | |||
{ | |||
| See Server Error information below |
Risk Factor (threatType) Scores
| Threat Type (AE.IP.threatType) | Score | SecureAuth IdP Risk Category | Definition |
|---|---|---|---|
| Anonymous Proxy | 100 | Extreme | Authentication is coming from a server that is designed to hide or anonymize the actual source IP Address |
| Attacker | 99 | Extreme | Indicators 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 |
| Compromised | 98 | Extreme | Indicators confirmed to host malicious content due to compromise or abuse – the exact time and length of compromise is unknown unless disclosed within the report |
| Related | 88 | High | Indicators likely related to an attack, but potentially only partially confirmed – detailed by one or more methods, like passive DNS, geo-location, and connectivity detection |
| Victim | 89 | High | Indicators representing an entity that has been confirmed to have been victimized by malicious activity, where actors have attempted or succeeded compromise |
| Uncategorized | 80 | High | Uncategorized threat |
threatCategory Scores
| Threat Category (AE.IP.threatCategory) | Response Value | Definition |
|---|---|---|
| Anonymous Proxy | 0 | Authentication is coming from a server that is designed to hide of anonymize the actual source IP Address |
| Cyber Espionage | 1 | Global issue with highly sophisticated nation-states and other actors targeting military, political, and commercial interests to gain decision advantage |
| Hacktivism | 2 | Activity ranges from nuisance level to sophisticated campaigns conducted by globally coordinated actors using increasingly sophisticated tools to negatively impact revenue or damage the brand |
| Enterprise | 3 | Threats specifically targeted at Enterprise |
| Critical Infrastructure | 4 | Threats specifically targeted at Critical Infrastructure |
| Cyber Crime | 5 | Threats typically orchestrated by criminal elements for financial benefit |
| Vulnerability and Exploitation | 6 | Threats targeting known software vulnerabilities |
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.
| HTTP Method | URI | Example |
|---|---|---|
| GET | /api/v1/dfp/js | https://secureauth.company.com/secureauth2/api/v1/dfp/js |
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 Reference | Provided by Application |
|---|---|
| fonts | host_address (IP Address of end-user client) |
| plugins | user_id |
| timezone | accept |
| video | accept_charset |
| local_storage | accept_encoding |
| session_storage | accept_language |
| ie_user_data | |
| cookie_enabled | |
| user_agent |
| HTTP Method | URI | Example |
|---|---|---|
| POST | /api/v1/dfp/validate | https://secureauth.company.com/secureauth2/api/v1/dfp/validate |
Compares the presented fingerprint with those stored in the user profile
Based on the information provided 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
| Function | JSON Parameters | Response |
|---|---|---|
| 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: {
Refer to the table in the /dfp/js endpoint section for more information on the required fingerprint components | { |
| 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: { | { |
{ | ||
{ |
| HTTP Method | URI | Example |
|---|---|---|
| POST | /api/v1/dfp/confirm | https://secureauth.company.com/secureauth2/api/v1/dfp/confirm |
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 Parameters | Success Response | Failure / Error Response |
|---|---|---|
{
"user_id": "<USERNAME>",
"fingerprint_id": "<FP ID>"
}
Example: { | { | { |
{ |
If a server error is encountered, then the follow response is returned:
{
"status": "server_error",
"message": "<Exception message describing the issue.>",
}
HTTP Status 500
Refer to Behavioral Biometrics Guide for more information on the feature
| HTTP Method | URI | Example |
|---|---|---|
| GET | /api/v1/behavebio/js | https://secureauth.company.com/secureauth2/api/v1/behavebio/js |
Enables the application to retrieve the javascript reference that is required to gather and analyze a user's behavioral biometric profile
Using the reference, most of the data required for the POST and PUT endpoints are provided; but the remaining information (user ID, host address, and user agent) must be provided by the application
Response to request:
{
"src": "https://SecureAuthIdPFQDN/SecureAuthIdPRealm/assets/scripts/api/behaveBio.obf.js?ver=9.0.0.22"
}
<form>
...
<input id="password" class="form-control" type="password" name="loginForm:Password" autocomplete="off" value="" placeholder="Password">
<input type="hidden" name="behavio_hidden" id="behavio_hidden">
<input id="textbox" class="form-control" type="text" name="loginForm:NotMonitored" autocomplete="off" value="" placeholder="Ignored">
...
</form>
<script>
$(document).ready(function() {
secureAuth.api.behaveBio({
anonymousByName: [],
anonymousById: [],
anonymousByType: ['password'],
behavioHiddenId: ['behavio_hidden'],
ignoreFields: ['loginForm:NotMonitored'],
haveMouse: false
});
});
</script>
Code Explanation
Form
<input type="hidden" name="behavio_hidden" id="behavio_hidden"> – Required anywhere in the <form> to create the behaviorProfile, with any preferred name and id values
<input id="password" class="form-control" type="password" name="loginForm:Password" autocomplete="off" value="" placeholder="Password"> – Example of input field with necessary components id, type, and name to identify anonymoustext fields
<input id="textbox" class="form-control" type="text" name="loginForm:NotMonitored" autocomplete="off" value="" placeholder="Not for Profile"> – Example of input field with necessary components id, type, and name to identify ignored fields
Script
Full script required in app code
anonymousByName – Identifies anonymoustext fields by name (in <input>)
anonymousById – Identifies anonymoustext fields by id (in <input>)
anonymousByType – Identifies anonymoustext fields by type (in <input>, as shown in code example)
behavioHiddenId – Calls to <input type="hidden" ...> line (required in <form>) with the same id value
ignoreFields – Identifies fields to not include in the behaviorProfile by name (in <input>, as shown in code example)
haveMouse – Monitors mouse movements as well as keystroke behavior (true or false)
| HTTP Method | URI | Example |
|---|---|---|
| POST | /api/v1/behavebio | https://secureauth.company.com/secureauth2/api/v1/behavebio |
| PUT | /api/v1/behavebio | https://secureauth.company.com/secureauth2/api/v1/behavebio |
The POST method collects and creates the user's behavioral biometric profile
The PUT method resets the user's profile to enable retraining
At this endpoint, the user's behavioral biometric profile is created and then analyzed against subsequent profile information posted to the endpoint.
To utilize Behavioral Biometrics as a second factor, training must occur, which is simply the API gathering user keystroke, text input, and other factors while they fill out the application's provided fields (e.g. username, password, home address, phone number, etc.). Once a profile has been trained, the API can then return a score based on the comparison of the "normal" behavior and the current behavior. To achieve a fully trained profile, the fields must be filled out ten (10) times.
Definitions
userID: User's username
behaviorProfile: User's behavioral biometric profile, generated by the javascript reference acquired in the /behavebio/js endpoint
hostAddress: User's IP Address
userAgent: User's user agent (computer / browser information)
TotalScore: How similar the presented behavior is to the stored profile
TotalConfidence: How confident the API is that the score is accurate
Device: Type of device user employs
Results: Breakdown of specific field scores
| JSON Parameters | Success Response | Failure / Error Response |
|---|---|---|
{
"userId":"<USERNAME>",
"behaviorProfile":'<BEHAVIORAL BIOMETRIC PROFILE>',
"hostAddress":"<IP ADDRESS>",
"userAgent":"<USER AGENT>"
}
Example: { | Untrained Profile: {
"BehaviorBioResults": {
"TotalScore": 0.5,
"TotalConfidence": 0,
"Device": "DESKTOP",
"Results": []
},
"status": "valid",
"message": ""
} | {
"status": "invalid",
"message": "Request validation failed with: userId was not present."
} |
Trained Profile: {
"BehaviorBioResults": {
"TotalScore": 0.999999780,
"TotalConfidence": 0.999780,
"Device": "DESKTOP",
"Results": [
{
"ControlID": "text#UserID",
"Score": 0.99997949,
"Confidence": 0.9997949,
"Count": 10
},
{
"ControlID": "password#Password",
"Score": 0.99997807,
"Confidence": 0.9997807,
"Count": 10
}
]
},
"status": "valid",
"message": ""
} | {
"status": "invalid",
"message": "Request validation failed with: behaviorProfile was not present."
} | |
{
"status": "invalid",
"message": "Request validation failed with: hostAddress was not present."
} | ||
{
"status": "invalid",
"message": "Request validation failed with: userAgent was not present."
} |
At this endpoint, the user's trained profile information can be reset; this is especially useful after a user changes a password
A profile can be completely reset, or specific fields from which behavior profile information is collected can be reset individually
Definitions
fieldName: Name of field to reset (unique to application); or set to ALL for global reset
fieldType: Type of field, either regulartext (actual values stored in profile) or anonymoustext (no actual values stored in profile, e.g. password entries); or set to ALL for global reset
deviceType: Type of device used by user (Desktop or Mobile); or set to ALL for global reset
| JSON Parameters | Success Response | Failure / Error Response |
|---|---|---|
{
"userId":"<USERNAME>",
"fieldName":"<FIELD TO RESET>",
"fieldType":"<TYPE OF FIELD>",
"deviceType":"<TYPE OF DEVICE>"
}
Specific Field Reset Example: {
userId:"jsmith",
fieldName:"UserID",
fieldType:"regulartext",
deviceType:"DESKTOP"
}Global Reset Example: {
userId:"jsmith",
fieldName:"ALL",
fieldType:"ALL",
deviceType:"ALL"
} | {
"status": "valid",
"message": "Reset sent to data store"
} | {
"status": "invalid",
"message": "Request validation failed with: userId was not present."
} |
{
"status": "invalid",
"message": "Request validation failed with: fieldName was not present."
} | ||
{
"status": "invalid",
"message": "Request validation failed with: fieldType was not present."
} | ||
{
"status": "invalid",
"message": "Request validation failed with: deviceType was not present."
} |