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.
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 theDatatab 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
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
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.
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?"
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.
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
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.
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.
End-user continues onto the configured workflow (Failure Action: Resume auth in Web Admin)
End-user bypasses 2-Factor Authentication and moves forward to next workflow step, e.g. password (Failure Action: Step down auth in Web Admin)
End-user undergoes additional 2-Factor Authentication (Failure Action: Step up auth in Web Admin)
End-user is taken directly to post-authentication target, bypassing additional analysis or 2-Factor Authentication (Failure Action: Post auth in Web Admin)
End-user is stopped immediately in the workflow and cannot continue (Failure Action: Hard Stop in Web Admin)
End-user is redirected to URL provided, e.g. another SecureAuth IdP realm (Failure Action: Redirect in Web Admin)
End-user must undergo 2-Factor Authentication and then provide password
End-user must provide password
End-user must undergo 2-Factor Authentication
End-user is not required to perform authentication or password validation
End-user is stopped immediately in workflow and cannot continue
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.
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.
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.
For example: https://secureauth.company.com/secureauth2/api/v1/dfp/js
// 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.
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.
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
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.