Previous User Authentication API
Warning
January 12, 2024
The APIs in this topic are deprecated and should not be used.
Note
For an overview of the Authentication API, including a glossary of terms and prerequisites, see Authentication API.
Authenticate with options
Sends an authentication request to Arculix and obtains the authentication channel; this channel must be used for checking the authentication result after MFA is complete. After receiving this response, the relying party should save the channel in a session and redirect the user to the “Select Your Authenticator” MFA page:
https://mfa.acceptto.com/mfa/index?channel=<channel_received_in_response>&callback_url=<https://yourdomain.com/auth/mfa_callback>
This page allows the user to choose their second-factor authentication method. Based on the policies defined by the relying party, the user has the option of using Push Notification, Email, Text Message, Voice Call, or TOTP for replying to the authentication request. As soon as the user selects “Accept” or “Decline” on the push, or verifies with a one-time passcode, the user is redirected back to the callback_url that was passed by the relying party.
The relying party should check the result of the MFA on the callback page to see if it was approved or rejected by the user.
Customized Authentication Flow
Instead of redirecting to the Arculix "Select Your Authenticator" page, the relying party can choose to specify the auth_type for the user during the initial authentication request and provide the user with an appropriate UI to respond. If the selected authentication type is a Push Notification, this UI should be a prompt for the user to check their Arculix Mobile app for an incoming request. Otherwise, it should be an interface where the user can enter the code provided to them via the selected method and verify that OTP with Arculix. This UI should also include JavaScript that waits to be notified by Arculix when the pending request has been resolved or expires.
auth_type | Description |
|---|---|
1 | Push Notification via Arculix Mobile |
2 | Text message (SMS) |
3 | Voice call |
4 |
Request
Method | URL |
|---|---|
POST |
|
Field | Type | Description |
|---|---|---|
String | Email address of the user being authenticated by the relying party | |
message | String | The message to deliver to the user. This message gets delivered to the user's device via push notification or SMS. e.g., “Would you like to sign into Website X?”. This can also be configured on a per-application basis via Arculix |
uid | String | Unique ID of the relying party application that is performing the authentication |
secret | String | Unique secret of the relying party application that is performing the authentication |
type | String | Type of authentication/authorization. User will see this value as the type of transaction on mobile app. for example: Login, Payment, ... |
timeout | Integer | The timeout value for the authentication request in seconds; if the user does not respond within the specified time, the request expires. The default value is 300 seconds (5 minutes) |
auth_type | Integer | The relying party can specify an |
ip_address | String | The end user's IP address, to be used for policy-based risk assessment and logging |
remote_ip_address | String | The end user's remote IP address (IP behind proxy) for enabling IP based policies and logging |
jwt | String | The value of the Arculix Device & Browser Fingerprint (DBFP) cookie, if in use; see MFA integration with device browser fingerprint for details |
totp | String | Users can be authenticated via TOTP by allowing them to enter their time based one-time passcodes while signing in. When TOTP is specified and is correct, the status of the response is approved. If the TOTP is incorrect, the authentication request will be rejected and no other MFA method will be offered |
Sample Request
{
"email": "abe.lincoln@example.com",
"message": "Would you like to sign in to Website X?",
"uid": "xxxa030e8ea-c2da-4678-90d9-3d734af4f42fxxx",
"secret": "xxxb141F9fb-c2da-4678-90d9-3d734af4f42fxxx",
"type": "Login",
"timeout": 120,
"ip_address": "1.1.1.1",
"remote_ip_address": "1.1.1.1"
}
Response
Successful Response
Field | Type | Description |
|---|---|---|
channel | String | All further API calls related to this authentication request must utilize this channel |
status | String | Status of the authentication request, one of |
auth_options | Array | Allowed authentication methods for the MFA step |
loa_score | Float | Level of assurance score returned from Arculix Risk Engine: e.g. |
meta_data | JSON | Metadata available to Arculix for this authentication |
event | String | Authentication event, possible values: |
risk_analyzers | JSON | List of risk analyzers that participated in calculating the LOA score |
policies_applied | JSON | If policies were applied to authentication request, the names and descriptions of the policies will be returned here as an array |
policies_matched | JSON | If policies matched the authentication request, the names and descriptions of the policies will be returned here as an array. This can include policies that were not applied; for instance, if both an auto-accept and force OOB policy matched the request, only the force OOB policy will be applied |
session_uid | String | ID of this authentication session, useful for continuous authentication |
user_email | String | Email address of the user that is authenticating |
expires_at | String | Timestamp that the authentication request will expire, in ISO 8601 format |
Successful Response Example
HTTP/1.1 200 OK
{
"success": true,
"response_code": "success",
"message": "",
"channel": "xxx6910423f49963ade2d1951359b1fe15fcxxxxxxxx",
"status": "pending",
"meta_data": {
"totp": "000000",
"type": "Login",
"timeout": "60",
"ip_address": "1.1.1.1",
"auth_loa_score": "0.0",
"policies_applied": [],
"remote_ip_address": "1.1.1.1",
"policy_automatic_action": null
},
"session_uid": 10037,
"user_email": "abe.lincoln@example.com",
"device_id": 0000,
"user_id": 0000,
"arculix_user_id": 0000,
"event": "auth",
"risk_analyzers": [
{
"id": 1,
"name": "Auth Method Risk Analyzer",
"class_name": "RiskAuthMethodAnalyzer",
"loa_delta": 2.0,
"data": {"auth_method":"push"},
"reasons": { "push": 2 }
},
{
"id": 2,
"name": "IP Risk Analyzer",
"class_name": "RiskIpAnalyzer",
"loa_delta": 0,
"data": {
"ip_address": "74.50.231.26"
},
"reasons": {
"first_time_user_ip_address": 0
}
},
{
"id": 3,
"name": "AIML Risk Analyzer",
"class_name": "RiskAimlAnalyzer",
"loa_delta": 0.489827692981322,
"data": {
"message": "",
"success": true,
"loa_score": "0.48982769298132156"
},
"reasons": {}
},
{
"id": 4,
"name": "DBFP",
"class_name": "RiskDbfpAnalyzer",
"description": "Provides LOA Score Analysis based on Browser fingerprints",
"loa_delta": 0.0,
"data": {
"hash1": "e9d72b3a698ccde626fb4c95835ef488",
"hash2": "1e6c91f627f0d962698cfb267cd89eeb",
"hash3": "2c59a5ca4240fa68d07d537d769cb53c",
"hash4": "48bcd22cd441408ba438a64929185b75",
"fingerprint": "207c2336ee2f53b6c66be5f2636d04af"
},
"reasons": {}
}
],
"policies_applied": [
{
"id": 7,
"name": "Force Out of band for new browsers SSO",
"description": "This policy forces out of band for new browsers on SAML Logins",
"action": "force_oob",
"class_name": "ConditionalPolicy/Policy/UserPolicy"
}
],
"policies_matched": [
{
"id": 7,
"name": "Force Out of band for new browsers SSO",
"description": "This policy forces out of band for new browsers on SAML Logins",
"action": "force_oob",
"class_name": "ConditionalPolicy/Policy/UserPolicy"
},
{
"id": 9,
"name": "Auto Approve good LOA score",
"description": "Minimize the friction when user has a good LOA score",
"action": "accept",
"class_name": "ConditionalPolicy"
}
],
"loa_score": 2.0,
"auth_options": ["push", "totp"],
"expires_at": "2020-02-11T10:23:57-08:00",
"notification_type": "push"
}
Unsuccessful Response
Field | Type | Description |
|---|---|---|
response_code | String | Error response code such as |
success | Boolean |
|
status | String | Status of the authentication request, always |
message | String | Informative message describing the error |
Unsuccessful Response Example
HTTP/1.1 401
{
"response_code": "user_not_found",
"success": false,
"status": "rejected",
"message": "abe.lincoln@example.com is not a valid registered Arculix account!"
}
HTTP/1.1 403
{
"response_code": "invalid_uid_secret",
"success": false,
"status": "rejected",
"message": "Invalid uid and secret combination, Application not found!"
}
Verify One Time Passcode
As discussed above, if the relying party specifies an authentication method for the user that requires a one time passcode (OTP) it should show a textbox to the user to enter the OTP that the user received via email, phone call or SMS. The relying party can then use the otp_verify method to check if the value entered by the user is correct or not. The maximum number of retry attempts for an OTP is 3 times; after three unsuccessful attempts, the authentication status becomes rejected.
Please note that one-time passcodes are different from TOTPs (Time-based one-time passwords) that users have in the Arculix Mobile app. Users can add Arculix's TOTP seed to any authenticator app and it can be verified in the same manner.
Request
Method | URL |
|---|---|
POST |
|
Field | Type | Description |
|---|---|---|
channel | String | The identifier for this authentication event, returned by |
String | The user's email | |
otp | String | The OTP sent to the user via email, phone call or SMS text message. |
Sample Request
{
"channel": "xxx6910423f49963ade2d1951359b1fe15fcxxxxxxxx",
"email": "abe.lincoln@example.com",
"otp": "123456"
}
Response
Successful Response
Field | Type | Description |
|---|---|---|
status | String |
|
message | String | Descriptive message for the result of the verification request. |
Successful Response Example
Correct Passcode
{
"status": "approved",
"message": "Your Authorization Request Was Successful!"
}
Incorrect Passcode
{
"status": "pending",
"message": "Invalid passcode was specified, please try again!"
}
Max Retry
{
"status": "rejected",
"message": "Maximum PIN attempts exceeded. Authorization request denied."
}
Unsuccessful Response
Field | Type | Description |
|---|---|---|
response_code | String | Error response code such as |
success | Boolean |
|
status | String | Status of the authentication request |
message | String | Informative message describing the error |
Unsuccessful Response Example
HTTP/1.1 401
{
"response_code": "user_not_found",
"success": false,
"status": "rejected",
"message": "abe.lincoln@example.com is not a valid registered Arculix account!"
}
HTTP/1.1 200
{
"response_code": "mfa_not_found",
"success": false,
"status": "Transaction not found!",
"message": "Transaction not found!"
}
Notification
After initiating an authentication request, the relying party has the option of getting notified as soon as the MFA phase is complete. This can be a result of the user taking action to approve or reject the request or the request having expired.
To listen for the notification, the relying party should use the channel received in the response from authenticate_with_options to subscribe to the Arculix Faye server. Use the following JavaScript snippet (written using jQuery but vanilla JavaScript works as well).
<script src="https://faye.acceptto.com/faye/faye.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<script type="text/JavaScript">
$(function() {
var faye = new Faye.Client("https://faye.acceptto.com/faye");
faye.subscribe("/messages/<%= @channel %>", function (data) {
window.location.reload(); // refresh the page and call check api on refresh
});
});
</script>
As soon as the MFA phase is complete, a notification is sent to Faye which relays it to any relying party subscribed to the channel and the code block inside faye.subscribe executes. Make sure that you are replacing the <%= @channel %> with the channel returned by the authenticate_with_options call and customize the code block inside faye.subscribe; the method above simply refreshes the page but generally a redirection to a results page is used. You can call the check API on page load to see the result of authentication.
Check authentication result
When the MFA phase is complete and the user has been returned to the callback_url or the relying party has been notified that a result is ready, the final status of the authentication is available via check.
Request
Method | URL |
|---|---|
POST |
|
Field | Type | Description |
|---|---|---|
channel | String | The identifier for this authentication event, returned by |
String | Email address of the user being authenticated by the relying party |
Sample Request
{
"channel": "xxx6910423f49963ade2d1951359b1fe15fcxxxxxxxx",
"email": "abe.lincoln@example.com"
}
Response
Successful Response
Field | Type | Description |
|---|---|---|
channel | String | All further API calls related to this authentication request must utilize this channel. |
status | String | Status of an authentication request: |
success | Boolean | Always |
auth_options | Array | Allowed authentication methods for the MFA step |
out_of_band_method_name | String | The name of the method used for MFA |
loa_score | Float | Level of assurance score returned from Arculix Risk Engine: e.g. |
meta_data | JSON | Metadata available to Arculix for this authentication |
event | String | Authentication event, possible values: |
risk_analyzers | JSON | List of risk analyzers that participated in calculating the LOA score |
policies_applied | JSON | If a policy applied to authentication request, name of policy will be returned here as an array |
policies_matched | JSON | If a policy matched to authentication request, name of policy will be returned here as an array |
session_uid | String | ID of this authentication session, useful for continuous authentication. |
user_email | String | Email address of the user that is authenticating |
expires_at | String | Timestamp that the authentication request expires, in ISO 8601 format |
Successful Response Example
HTTP/1.1 200 OK
{
"success": true,
"response_code": "success",
"message": "",
"channel": "xxx6910423f49963ade2d1951359b1fe15fcxxxxxxxx",
"status": "approved",
"meta_data": {
"totp": "000000",
"type": "Login",
"timeout": "60",
"ip_address": "1.1.1.1",
"auth_loa_score": "0.0",
"policies_applied": [],
"remote_ip_address": "1.1.1.1",
"policy_automatic_action": null
},
"session_uid": 10037,
"user_email": "abe.lincoln@example.com",
"device_id": 0000,
"user_id": 0000,
"arculix_user_id": 0000,
"event": "post-auth",
"risk_analyzers": [
{
"id": 1,
"name": "Auth Method Risk Analyzer",
"class_name": "RiskAuthMethodAnalyzer",
"loa_delta": 2.0,
"data": {"auth_method":"push"},
"reasons": { "push": 2 }
},
{
"id": 2,
"name": "IP Risk Analyzer",
"class_name": "RiskIpAnalyzer",
"loa_delta": 0,
"data": {
"ip_address": "74.50.231.26"
},
"reasons": {
"first_time_user_ip_address": 0
}
},
{
"id": 3,
"name": "AIML Risk Analyzer",
"class_name": "RiskAimlAnalyzer",
"loa_delta": 0.489827692981322,
"data": {
"message": "",
"success": true,
"loa_score": "0.48982769298132156"
},
"reasons": {}
},
{
"id": 4,
"name": "DBFP",
"class_name": "RiskDbfpAnalyzer",
"description": "Provides LOA Score Analysis based on Browser fingerprints",
"loa_delta": 0.0,
"data": {
"hash1": "e9d72b3a698ccde626fb4c95835ef488",
"hash2": "1e6c91f627f0d962698cfb267cd89eeb",
"hash3": "2c59a5ca4240fa68d07d537d769cb53c",
"hash4": "48bcd22cd441408ba438a64929185b75",
"fingerprint": "207c2336ee2f53b6c66be5f2636d04af"
},
"reasons": {}
}
],
"policies_applied": [
{
"id": 7,
"name": "Force Out of band for new browsers SSO",
"description": "This policy forces out of band for new browsers on SAML Logins",
"action": "force_oob",
"class_name": "ConditionalPolicy/Policy/UserPolicy"
}
],
"policies_matched": [
{
"id": 7,
"name": "Force Out of band for new browsers SSO",
"description": "This policy forces out of band for new browsers on SAML Logins",
"action": "force_oob",
"class_name": "ConditionalPolicy/Policy/UserPolicy"
},
{
"id": 9,
"name": "Auto Approve good LOA score",
"description": "Minimize the friction when user has a good LOA score",
"action": "accept",
"class_name": "ConditionalPolicy"
}
],
"loa_score": 2.0,
"auth_options": ["push"],
"expires_at": "2020-02-11T10:23:57-08:00",
"notification_type": "push",
"out_of_band_method_name": "push"
}
Unsuccessful Response
Field | Type | Description |
|---|---|---|
response_code | String | Error response code such as |
success | Boolean |
|
status | String | Status of the authentication request |
message | String | Informative message describing the error |
Unsuccessful Response Example
HTTP/1.1 401
{
"response_code": "user_not_found",
"success": false,
"status": "rejected",
"message": "abe.lincoln@example.com is not a valid registered Arculix account!"
}
HTTP/1.1 200
{
"response_code": "mfa_not_found",
"success": false,
"status": "Transaction not found!",
"message": "Transaction not found!"
}
Log in with QR Code
Instead of entering a username and password, users with the Arculix Mobile app can scan a QR code, receive a push notification on their device, approve it and sign in, all without a single keystroke.
Using the JavaScript snippet below, relying parties can generate and show an Arculix compatible QR code to users for login:
<script src="https://faye.acceptto.com/faye/faye.js"></script> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script> <script type="text/JavaScript"> $(function() { var uid = "xxxxxx8d7efa41516c37319bc85b8979ee2891aac01c0aba01c28ed6c3xxxxx"; // Unique ID of the relying party application var faye = new Faye.Client("https://faye.acceptto.com/faye"); var hex1 = Math.floor(Math.random()*16777215).toString(16); var hex2 = Math.floor(Math.random()*16777215).toString(16); var date_obj = new Date(); var time_since_epoch = date_obj.getTime(); var channel = time_since_epoch + hex1 + hex2; var qrcodeJSON = '{ "app_uid":"' + uid + '", "channel":"' + channel + '" }'; var qrcode = window.btoa(qrcodeJSON); var qr_url = "https://chart.apis.google.com/chart?cht=qr&chs=220x220&chld=H|0&chl=" + qrcode; $('#login_qrcode').attr("src", qr_url); faye.subscribe("/messages/" + channel, function (data) { window.location.replace("https://yourdomain.com/qrcode/channel?channel=" + channel); }); }); </script> <center> <img id="login_qrcode" alt="qrcode"> </center>In the Faye callback function, replace the
https://yourdomain.com/qrcodepath with a path handled by the relying party application. When the user scans the QR code with Arculix Mobile, a notification will be sent to the subscribed Faye channel.After redirection, the relying party should pass the channel to the Arculix
get_user_by_websocket_channelAPI in order to get the email address of the Arculix Mobile user who performed the QR scan.After getting the user’s email address, the relying party should call the
authenticateAPI and continue as if the user entered their username and password. Since users are scanning the QR codes using their trusted mobile devices on the Arculix Mobile app, this process eliminates the friction of entering usernames and passwords.
Request
Method | URL |
|---|---|
POST |
|
Field | Type | Description |
|---|---|---|
websocket_channel | String | The |
uid | String | Unique ID of the relying party application that is performing the authentication |
secret | String | Unique secret of the relying party application that is performing the authentication |
Sample Request
{
"websocket_channel": "xxx6910423f49963ade2d1951359b1fe15fcxxxxxxxx",
"uid": "xxxa030e8ea-c2da-4678-90d9-3d734af4f42fxxx",
"secret": "xxxb141F9fb-c2da-4678-90d9-3d734af4f42fxxx"
}
Response
Successful Response
Field | Type | Description |
|---|---|---|
success | Boolean |
|
message | String | Blank for successful requests |
user_email | String | Email address of the user who scanned the QR code on Arculix Mobile. |
user_id | Integer | Arculix user ID for the user who scanned the QR code on Arculix Mobile. |
Successful Response Example
{
"success": "true",
"message": "",
"user_email": "abe.lincoln@example.com",
"user_id": 0000
}
Unsuccessful Response
Field | Type | Description |
|---|---|---|
response_code | String | Error response code such as |
success | Boolean |
|
user_email | String | Blank for unsuccessful requests |
message | String | Informative message describing the error |
Unsuccessful Response Example
HTTP/1.1 200
{
"success": false,
"user_email": "",
"message": "Websocket channel not found or user not assigned to channel yet!"
}
HTTP/1.1 403
{
"response_code": "invalid_uid_secret",
"success": false,
"status": "rejected",
"message": "Invalid uid and secret combination, Application not found!"
}
User account status
Before using Arculix as an MFA provider, the relying party has the option of checking to see if the user is registered with Arculix and has a valid account and an active paired device.
Request
Method | URL |
|---|---|
POST |
|
Field | Type | Description |
|---|---|---|
String | The email address of the user of the relying party which is being verified on Arculix | |
uid | String | Unique ID of the relying party application that is performing the authentication |
secret | String | Unique secret of the relying party application that is performing the authentication |
Sample Request
{
"email": "abe.lincoln@example.com",
"uid": "xxxa030e8ea-c2da-4678-90d9-3d734af4f42fxxx",
"secret": "xxxb141F9fb-c2da-4678-90d9-3d734af4f42fxxx"
}
Response
Successful Response
Field | Type | Description |
|---|---|---|
valid | Boolean | True if the user and the application indicated by the UID and secret are both present on Arculix, False otherwise |
registration_state | String | The current registration state of the user, could be one of these states: |
device_paired | Boolean | Indicates whether the user has an active device paired with the Arculix Mobile app |
Response Examples
Fully Registered
{
"valid": true,
"registration_state": "finished",
"device_paired": true
}
User or Application not found
{
"valid": false,
"registration_state": "",
"device_paired": false
}
Confirmed email and phone number
{
"valid": true,
"registration_state": "waiting_for_security_questions",
"device_paired": false
}
No confirmed email address
{
"valid": true,
"registration_state": "waiting_for_email_confirm",
"device_paired": false
}
Calculate LOA Score (Risk Engine)
If the organization and relying party application have access to a standalone risk engine license, the relying party application can submit raw request information to the Arculix API to calculate the LOA score for the current session. This score is calculated based on the history and normality of user behavior and information collected from each user from different sources such as AI/ML Engine, user browser fingerprint, geo-location networking information, etc.
This API can be used for continuous authentication to calculate the LOA score based on changes to the session and request context. For example, a change in IP address or browser fingerprint or GPS location of the user can have an impact on the current session’s LOA score. The API can also be used for sending data to the risk engine from native or web applications that don't have a direct integration with Arculix mobile SDK or single sign-on solution.
Note
In order for the calculate LOA score API to work, the application — specified via uid and secret in the request body — must have permission to send data to the risk_engine.
Request
Method | URL |
|---|---|
POST |
|
Field | Type | Description |
|---|---|---|
uid | String | Unique ID of the relying party application that is performing the authentication |
secret | String | Unique secret of the relying party application that is performing the authentication |
String | User's email address. Email domain should belong to the organization. | |
session_uid | String | A unique identifier for the session. This is the unique value that the relying party should generate for the lifetime of a session and should be unique across the relying party organization between different applications. |
event | String | The authentication event, possible values are |
context | JSON | The context of the authentication request should contain all the key/values the relying party has from the user’s request. Depending on the keys present in this parameter, the Arculix risk engine decides which risk analyzers need to be engaged in calculating the final LOA score. For the list of possible key-value pairs, see the table below. |
Note
If you want the risk engine to mark the data provided — such as IP, location, DBFP, etc — as trusted for future MFAs use post-auth for the value of the event key. Data from all other events will be discarded.
Context
Arculix's risk engine captures and stores any key/value sent to this API but certain keys have special meanings and are used by existing risk analyzers to calculate the LOA score for the request. Here is the list of keys and the corresponding risk analyzers which are looking for the key in the context.
Key | Description | Risk Analyzer |
|---|---|---|
ip_address | The public IP address of the end-user. | IP Risk Analyzer |
latitude | The GeolocationCoordinates.latitude property is a double-precision floating point value which represents the latitude of a geographical position, specified in decimal degrees. | Location Risk Analyzer |
longitude | The GeolocationCoordinates.longitude property is a double-precision floating point value which represents the longitude of a geographical position, specified in decimal degrees. | Location Risk Analyzer |
accuracy | The GeolocationCoordinates.accuracy attribute denotes the accuracy level of the latitude and longitude coordinates in meters (e.g., 65 meters). Arculix will discard the geolocation information if accuracy is above a certain threshold. By default this number is 100 and any data with accuracy above 100 will be discarded. | Location Risk Analyzer |
bfpToken | When integrating with the Arculix DBFP JavaScript plugin, the DBFP engine will create a cookie named | DBFP Risk Analyzer |
user_agent | A characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent. | DBFP Risk Analyzer |
oob_name | Out-of-band method used during authentication. Currently supported values are: | Auth Method Risk Analyzer |
mobile_device.device_uuid | A universally unique mobile device identifier if the data is coming from a native mobile application. | Device Trust |
mobile_device.device_type | Model information of the mobile device. e.g. iPhone 11 | Device Trust |
mobile_device.app_version | Native mobile application version number that is sending the information. | Device Trust |
mobile_device.os_type | Mobile device operating system. e.g. iOS/Android | Device Trust |
mobile_device.os_version | Operating system version of the mobile device. e.g. 14.5.1 | Device Trust |
mobile_device.device_brand | Maker of the mobile device. e.g. Apple/Samsung/Google/... | Device Trust |
mobile_device.ip_address | IP address of the mobile device. | Device Trust |
mobile_device.remote_ip_address | X-Forwarded-For or the source IP address of a client connecting to a web server through an HTTP proxy or a load balancer. | Device Trust |
mobile_device.locations | List of Geolocation coordinates information captured by the mobile device (Requires user consent and permission). See Sample Mobile Request for details. | Device Trust |
mobile_device.locations.latitude | The latitude property is a double-precision floating point value which represents the latitude of a geographical position, specified in decimal degrees. | Location Risk Analyzer |
mobile_device.locations.longitude | The longitude property is a double-precision floating point value which represents the longitude of a geographical position, specified in decimal degrees. | Location Risk Analyzer |
mobile_device.locations.log_date | The timestamp at which coordinates data was collected from the user's mobile device. Timestamp should be in ISO8601 format. | Location Risk Analyzer |
Note
If the context contains the mobile_device key, the type of application in Arculix should be set as mobile_application; otherwise Arculix will discard the mobile_device key data.
Sample Web Request
{
"session_uid":"xxxxx1f1f5a634355702ced92951xxxx",
"uid":"xxxxxx87408fb703a79fe63c967f7120da0fe92b5b2a2c43c303524xxxxxx",
"secret": "xxxxxxafa152450653d7387d8f42698bfa3557f0d9e791a83231d0a8aec6xxxxxx",
"email":"jian-yang@piedpiper.com",
"event": "post-auth",
"context": {
"ip_address":"74.50.231.26",
"latitude": 50.09951255599202,
"longitude": -120.98416469567863,
"accuracy": 50,
"bfpToken": "xxxxbGciOiJIUzI1NiJ9.xxxxxW5nZXJwcmludCI6IjA3NmIzNWIwNjQ3NzkyNzAyYTk2NmMzMWUwMTY5ZjNiIiwiaGFzaDEiOiJkOWUwNWFhZDM3MmQwODM4YzIyZWNiYjI3MjZmYzY0YSIsImhhc2gyIjoiYmNiNmYyMzVkZTM2YmU5NWY5Yjk4YTE5ZGI5NmQwZjIiLCJoYXNoMyI6IjhkYjljYWY2YWM1MzYzYzAwZmFmZGEzZjdlYzFkN2FiIiwiaGFzaDQiOiJhMzU4ZDUyNjkyNjAyNDRjYTA0MDdmZDIxYzRhNjYwOCIsInJpc2siOjAuNSwiYnJvd3Nlcl9vdXRkYXRlZCI6ZmFsc2V9.l5U-KSI5A1fEz2R9HD6CiViCF9VFfaWLG3BlweYZkoo",
"auth_method": "totp",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0.3 Safari/605.1.15"
}
}
Sample Mobile Application Request
{
"uid":"xxxxxx87408fb703a79fe63c967f7120da0fe92b5b2a2c43c303524xxxxxx",
"secret": "xxxxxxafa152450653d7387d8f42698bfa3557f0d9e791a83231d0a8aec6xxxxxx",
"email":"jian-yang@piedpiper.com",
"session_uid": "session-5faaa6cf22b9d6351c5794de399e33a1",
"event": "post-auth",
"context": {
"mobile_device":
{
"device_uid": "D0C3EABF-40D0-4EDE-8DC6-0AB758C82AF0",
"device_type": "iPhone 11",
"app_version": "6.2.0",
"os_type": "iOS",
"os_version": "13.3",
"device_brand": "Apple",
"ip_address": "70.69.146.204",
"remote_ip_address": "192.168.1.210",
"locations": [
{
"log_date": "2021-05-12T21:56:00+00:00",
"latitude": 50.09951255599202,
"longitude": -120.98416469567863
},
{
"log_date": "2021-05-12T10:29:00-07:00",
"latitude": 51.09951255599202,
"longitude": -123.98416469567863
}
]
}
}
}
Response
Successful Response
Field | Type | Description |
|---|---|---|
success | Boolean |
|
loa_score | Float | LOA score calculated by the risk engine based on the parameters provided in the request context. |
message | String | Blank for successful requests |
id | Integer | Internal risk session ID |
risk_analyzers | Array | Risk analyzer result objects describing the reason behind the LOA score |
Successful Response Example
{
"id": 100,
"message": "",
"success": true,
"loa_score": 2.9,
"risk_analyzers": [
{
"id": 1,
"data": {
"hash1": "6a5057d0727ba9e96c9c64ad174518f5",
"hash2": "75d9149d8bb2316b34dc1bf642c7ce84",
"hash3": "95a4eba02f8986ba7e74cca5450219c1",
"hash4": "48bcd22cd441408ba438a64929185b75",
"fingerprint": "f834686715c5aefd0109e337e2f9fe14"
},
"name": "DBFP",
"reasons": {
"hash2": 1,
"hash4": 0.25,
"matched_via": "hash4,hash2",
"matched_dbfp_id": 3082
},
"loa_delta": 1.25,
"class_name": "RiskDbfpAnalyzer",
"updated_at": "2021-02-12T17:52:12.607-08:00",
"description": "Provides LOA Score Analysis based on Browser fingerprints"
},
{
"id": 4,
"data": {
"mobile_vs_auth_request_distance_in_meters": 6.16
},
"name": "GPS",
"reasons": {
"mobile_browser_proximity": "6.16 meters"
},
"loa_delta": 4,
"class_name": "RiskLocationAnalyzer",
"updated_at": "2021-02-12T17:52:12.616-08:00",
"description": "Provides LOA Score Analysis based on the GPS coordinates of requests"
},
{
"id": 2,
"data": {
"ip_address": "76.115.75.122"
},
"name": "IP",
"reasons": {
"known_exclusive_user_ip_address": 4
},
"loa_delta": 4,
"class_name": "RiskIpAnalyzer",
"updated_at": "2021-02-12T17:52:12.631-08:00",
"description": "Provides LOA Score Analysis based on the IP address of requests"
}
]
}
Unsuccessful Response
Field | Type | Description |
|---|---|---|
success | Boolean | Always |
loa_score | Integer | 0 for unsuccessful requests |
message | String | Informative message describing the error |
Unsuccessful Response Example
HTTP/1.1 401
{
"success": false,
"loa_score": 0.0,
"message": "Risk Engine APIs are not enabled for this application. please contact support@secureauth.com for more information."
}
HTTP/1.1 403
{
"success": false,
"loa_score": 0.0,
"message": "Invalid uid and secret combination, Application not found!"
}
HTTP/1.1 422
{
"success": false,
"loa_score": 0.0,
"message": "Email domain is not owned by your organization."
}
HTTP/1.1 422
{
"success": false,
"loa_score": 0.0,
"message": "Unable to create the user with 1234-xyz: Invalid email address format."
}
MFA integration with device browser fingerprint
Use the following steps to integrate MFA with DBFP.
In the body element of your HTML page, add the following DBFP JavaScript file script:
<!-- Arculix DBFP --> <script type="text/JavaScript" src="https://dbfp.acceptto.com/bfp6.js"></script> <!-- End Arculix DBFP -->
This script sets a cookie named jwt that can be passed as a parameter to the initial user authentication APIs using the key
bfpTokenorjwt. Arculix uses this data to assess the risk of the authentication request including browser fingerprint, IP address of user and GPS location of the user’s browser. The server compares this data with the history of user behavior data to detect anomalies.Save your changes.