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 generate One-time Passwords (OTPs) delivered via
Push / Push-to-Accept Notification
can analyze a user's access attempt through SecureAuth's
Device / Browser Fingerprinting
Behavioral Biometric profile
can evaluate IP address risk through threat intelligence data
can prevent end-users from logging on a realm
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 v9.1 or later
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
Configure Response Header
SecureAuth's API includes a security hashing enhancement that ensures the integrity of the information being sent in all of the endpoints' responses from the appliance to the application.
Through a hashing algorithm, SecureAuth IdP delivers a signature that can be validated by the application to ensure that no data manipulation has occurred prior to the application consuming the data.
Before sending the response to the application (initiated by the endpoint request), SecureAuth IdP creates the signature and includes it in the Response Header (prepended by X-SA-SIGNATURE:). The application can then validate the response by hashing the date / time and content from the consumed response and the Application ID with the Application Key and compare the new hashed value with the X-SA-SIGNATURE value.
The Application ID and Application Key are generated in SecureAuth IdP and connect the appliance with the application for each endpoint transaction
If, after hashing the data, the value matches (exactly) the signature provided in the SecureAuth IdP response header, then the data has not been compromised; if the value does not match the response signature, then the data has been modified.
Application Response Header
In the application's code, the following is required to validate the response header's signature:
1. Build a string based on the request
a. X-SA-DATE for a second-precision timestamp (from the SecureAuth IdP v.1+ response)
b. APPLICATION ID (from SecureAuth IdP Web Admin)
c. CONTENT (JSON Parameters from the SecureAuth IdP response)
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. Compare the HMAC SHA256 hash from step 3 to the X-SA-SIGNATURE value in the SecureAuth Response Header
5. Consume the response based on the comparison result
OPTIONAL: Configure X-SA-Ext-Date Header
The string section for DATE/TIME can be configured to use either the second-precision UTC time or the millisecond-precision format DateTime
If using the millisecond-precision, the date string must be included in the X-SA-Ext-Date header
Sample X-SA-Ext-Date Code
var dateMillis = request.Headers.Date.Value.UtcDateTime.ToString("ddd, dd MMM yyyy HH:mm:ss.fff G\\MT");
var httpMethod = request.Method.Method;
string uri = request.RequestUri.AbsolutePath;
string content = null;
if (request.Content != null)
content = request.Content.ReadAsStringAsync().Result;
result = (string.IsNullOrEmpty(content)) ?
string.Join("\n", httpMethod, dateMillis, appId, uri) :
string.Join("\n", httpMethod, dateMillis, appId, uri, content);
Configure the endpoint(s) for the selected feature