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
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 theDatatab in the SecureAuth IdP Web Admin
A directory integration is required for SecureAuth IdP to pull user profile information during the login process
A directory integration is required for the Authentication API, but SecureAuth's Web Service (Multi-Data Store) option is not supported
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
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
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
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.)
Fail / Error
"value": "What city were you born in?"
"value": "What was your favorite childhood game?"
"value": "What was your dream job as a child?"
"value": "Who is your personal hero?"
"value": "What is the last name of your favorite school teacher?"
"value": "What is the name of your favorite childhood pet?"
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
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
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
Validates auth information (e.g. username, password, etc.) and generates OTPs for authentication
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
New Functions Introduced in v9.0.2
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.
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.
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
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.
Authentication is coming from a server that is designed to hide or anonymize the actual source IP Address
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
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
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
Indicators representing an entity that has been confirmed to have been victimized by malicious activity, where actors have attempted or succeeded compromise
Threat Category (AE.IP.threatCategory)
Authentication is coming from a server that is designed to hide of anonymize the actual source IP Address
Global issue with highly sophisticated nation-states and other actors targeting military, political, and commercial interests to gain decision advantage
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
Threats specifically targeted at Enterprise
Threats specifically targeted at Critical Infrastructure
Threats typically orchestrated by criminal elements for financial benefit
Vulnerability and Exploitation
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.
// 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.
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.
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
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
<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
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)
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.
"message": "Request validation failed with: behaviorProfile was not present."
"message": "Request validation failed with: hostAddress was not present."
"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
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
Failure / Error Response
"fieldName":"<FIELD TO RESET>",
"fieldType":"<TYPE OF FIELD>",
"deviceType":"<TYPE OF DEVICE>"