User Authentication API

Introduction#

In order to leverage Acceptto’s eGuardian® engine to perform Multi-Factor Authentication for existing applications, a set of APIs are provided. The application (or "relying party") authenticates the user internally and then delegates the Smart MFA process to Acceptto. This is a three phase process which can be implemented in several different ways to meet the application's requirements.

Authentication Request - Details of the user, application, and context are submitted to eGuardian® to be processed by the risk engine and policy orchestration engine in order to generate a result and an LOA score
MFA - The user is required to perform an out of band verification step using Push, SMS, TOTP etc. This step may be bypassed if the Authentication Request is automatically approved by the policy engine
Result - The relying party is notified that the MFA phase has been completed and requests the result from eGuardian®, then allows or blocks user access to the application appropriately

Glossary#

LOA - A Level of Assurance, as defined by the ISO/IEC 29115 Standard, describes the degree of confidence in the processes leading up to and including an authentication. It quantifies assurance that the user claiming a particular identity is the user to which that identity was assigned. LOA is a number between 0 to 4, with 0 being minimal confidence in the asserted identity of the user and LOA level of 4 showing a very high confidence in asserted identity of the user.
OTP - A One-Time Passcode can be used to approve an authentication request. Users can have the OTP sent to them via SMS, voice call, or email.
Out-of-band - User authentication over a network or channel separate from the primary network or channel; used in multi-factor authentication.
Relying Party - The relying party is an organization or application which relies on Acceptto eGuardian® for doing multi-factor authentication.
Request - The request method, URL, and parameters
- All request parameters are mandatory unless explicitly marked as optional
- Each request parameter has a defined field, type, and description
Response - All the possible responses are listed for each method. Only one of them is issued per request.
- All responses are in JSON format.
Status - The HTTP status code of the response.
TOTP - A Time-based One-Time Password is a six-digit passcode that changes every 30 seconds. The eGuardian® TOTP seed can be added to the It'sMe app or any other compatible authenticator from the eGuardian® user dashboard.

Pre-Requisites#

An application created in the eGuardian® dashboard to correspond with the relying party application; this assigns a UID and secret which are required for most API calls
Users of the relying party application must be registered with eGuardian®

MFA Overview#

There are several different ways for a relying party to implement Acceptto's Smart MFA; here is one example of the steps in a typical flow.

The user identifies themselves to the relying party; this can be via username and password login or passwordless options such as QR scan login
The relying party initiates an authentication request with eGuardian®, including the user identifier and authentication context such as the Device Browser Fingerprint
eGuardian® responds to the authentication request with the result of analysis by the risk engine and policy orchestration, including whether the user must perform MFA
The relying party either redirects the user to the eGuardian® MFA page or provides their own authentication screen, where the user can select an out of band MFA method and provide a verification code or approve a push notification
eGuardian® notifies the relying party that the authentication request has been resolved and the relying party queries eGuardian® for the result
The relying party acts based on the authentication result: if it is approved, the user is allowed access to the application but if it is expired or rejected, the user's access is denied

Authenticate with options#

Sends an authentication request to eGuardian® 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 Acceptto "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 It'sMe 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 eGuardian®. This UI should also include Javascript that waits to be notified by eGuardian® when the pending request has been resolved or expires.

auth_type	Description
1	Push Notification via It'sMe
2	Text message (SMS)
3	Voice call
4	Email

Request#

Method	URL
POST	api/v9/authenticate_with_options

Field	Type	Description
email	String	Email address of the user being authenticated by the relying party
message `optional`	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 the eGuardian Dashboard
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 `optional`	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 `optional`	Integer	The relying party can specify an `auth_type` instead of presenting the user with a set of options in the MFA phase; see above for details
ip_address `optional`	String	The end user's IP address, to be used for policy-based risk assessment and logging
remote_ip_address `optional`	String	The end user's remote IP address (IP behind proxy) for enabling IP based policies and logging
jwt `optional`	String	The value of the eGuardian® DBFP cookie, if in use; see below for details
totp `optional`	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 `pending/approved/rejected/expired`. In the case of an auto-accept or auto-reject policy match, the status becomes `approved` or `rejected` immediately; otherwise, it should be `pending`
auth_options	Array	Allowed authentication methods for the MFA step
loa_score	Float	Level of assurance score returned from Acceptto Risk Engine: e.g. `2.5`
meta_data	JSON	Metadata available to eGuardian® for this authentication
event	String	Authentication event, possible values: `pre-auth`, `auth`, `post-auth`
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,  "eguardian_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 `invalid_uid_secret` or `user_not_found`
success	Boolean	`false`
status	String	Status of the authentication request, always `rejected` for unsuccessful authentication requests
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 Acceptto 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 It'sMe™ app. Users can add eGuardian®'s TOTP seed to any authenticator app and it can be verified in the same manner.

Request#

Method	URL
POST	api/v9/otp_verify

Field	Type	Description
channel	String	The identifier for this authentication event, returned by `authenticate_with_options`
email	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	`pending/approved/rejected/expired` status of the authentication request. If the OTP was correct, this will have changed to `approved`; if the user has reached the maximum number of incorrect attempts, it will have changed to `rejected`.
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 `mfa_not_found` or `user_not_found`
success	Boolean	`false`
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 Acceptto 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 eGuardian® 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	api/v9/check

Field	Type	Description
channel	String	The identifier for this authentication event, returned by `authenticate_with_options`
email	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: `approved/rejected/expired`.
success	Boolean	Always `true` for successful requests
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 Acceptto Risk Engine: e.g. `2.5`
meta_data	JSON	Metadata available to eGuardian® for this authentication
event	String	Authentication event, possible values: `auth`, `post-auth`
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,  "eguardian_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 `mfa_not_found` or `user_not_found`
success	Boolean	`false`
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 Acceptto 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 It'sMe 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 eGuardian® 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/qrcode path with a path handled by the relying party application. When the user scans the QR code with It'sMe, a notification will be sent to the subscribed Faye channel.

After redirection, the relying party should pass the channel to the eGuardian® get_user_by_websocket_channel API in order to get the email address of the It'sMe user who performed the QR scan.
After getting the user’s email address, the relying party should call the authenticate API 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 It’sMe app, this process eliminates the friction of entering usernames and passwords.

Request#

Method	URL
POST	api/v9/get_user_by_websocket_channel

Field	Type	Description
websocket_channel	String	The `channel` generated by the javascript snippet above.
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	`true`
message	String	Blank for successful requests
user_email	String	Email address of the user who scanned the QR code on It'sMe.
user_id	Integer	eGuardian® user ID for the user who scanned the QR code on It'sMe.

Successful Response Example#

{  "success": "true",  "message": "",  "user_email": "abe.lincoln@example.com",  "user_id": 0000}

Unsuccessful Response#

Field	Type	Description
response_code `optional`	String	Error response code such as `invalid_uid_secret`
success	Boolean	`false`
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 eGuardian® as an MFA provider, the relying party has the option of checking to see if the user is registered with eGuardian® and has a valid account and an active paired device.

Request#

Method	URL
POST	api/v9/is_user_valid

Field	Type	Description
email	String	The email address of the user of the relying party which is being verified on eGuardian®.
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 eGuardian®, False otherwise
registration_state	String	The current registration state of the user, could be one of these states: `finished`, `waiting_for_email_confirm`, `waiting_for_mobile_confirm`, `waiting_for_security_questions`. Anything other than `finished` means the user's profile is not yet complete; if a user's state is `waiting_for_email_confirm` they should not be considered as properly registered.
device_paired	Boolean	Indicates whether the user has an active device paired with the It'sMe 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 eGuardian® 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 eGuardian mobile SDK or Acceptto’s single sign-on solution.

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	api/v10/risk_engine/calculate_score

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
email	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 `pre-auth`, `auth`, `post-auth`, `cont-auth` (Continuous authentication).
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 eGuardian® 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.

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#

Acceptto'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). eGuardian 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 eGuardian® DBFP javascript plugin, DBFP engine will create a cookie named `jwt` cookie. The value of this cookie should be passed as `bfpToken` to the risk engine.	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: `push`, `fido_push`, `totp`, `sms`, `email`, `voice`, `fido_u2f`, `security_question`, `policy`, `static_pin`, `external_oob`.	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 originating 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

If the context contains the mobile_device key, the type of application in eGuardian dashboard should be set as mobile_application; otherwise eGuardian 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	`true`
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 `false` for unsuccessful requests
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@acceptto.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 DBFP#

Add the DBFP javascript file right before the closing body tag of your HTML page:

<!-- Acceptto  DBFP -->  <script type="text/javascript" src="https://dbfp.acceptto.com/bfp.js"></script><!-- End Acceptto  DBFP -->

This script sets a cookie named jwt that can be passed as a parameter to the authenticate_with_options or calculate_score APIs using the key bfpToken or jwt. eGuardian® 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.

Disclaimer#

All product names, trademarks, and registered trademarks are the property of their respective owners.

All company, product, and service names used in this document are for identification purposes only. The use of these names, trademarks, and brands do not constitute an endorsement by the Acceptto Corporation.