Skip to main content

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.

  1. 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
  2. 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
  3. 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#

  1. 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
  2. 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.

  1. The user identifies themselves to the relying party; this can be via username and password login or passwordless options such as QR scan login
  2. The relying party initiates an authentication request with eGuardian®, including the user identifier and authentication context such as the Device Browser Fingerprint
  3. 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
  4. 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
  5. eGuardian® notifies the relying party that the authentication request has been resolved and the relying party queries eGuardian® for the result
  6. 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_typeDescription
1Push Notification via It'sMe
2Text message (SMS)
3Voice call
4Email

Request#

MethodURL
POSTapi/v9/authenticate_with_options
FieldTypeDescription
emailStringEmail address of the user being authenticated by the relying party
message optionalStringThe 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
uidStringUnique ID of the relying party application that is performing the authentication
secretStringUnique secret of the relying party application that is performing the authentication
typeStringType of authentication/authorization. User will see this value as the type of transaction on mobile app. for example: Login, Payment, ...
timeout optionalIntegerThe 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 optionalIntegerThe 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 optionalStringThe end user's IP address, to be used for policy-based risk assessment and logging
remote_ip_address optionalStringThe end user's remote IP address (IP behind proxy) for enabling IP based policies and logging
jwt optionalStringThe value of the eGuardian® DBFP cookie, if in use; see below for details
totp optionalStringUsers 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#

FieldTypeDescription
channelStringAll further API calls related to this authentication request must utilize this channel
statusStringStatus 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_optionsArrayAllowed authentication methods for the MFA step
loa_scoreFloatLevel of assurance score returned from Acceptto Risk Engine: e.g. 2.5
meta_dataJSONMetadata available to eGuardian® for this authentication
eventStringAuthentication event, possible values: pre-auth, auth, post-auth
risk_analyzersJSONList of risk analyzers that participated in calculating the LOA score
policies_appliedJSONIf policies were applied to authentication request, the names and descriptions of the policies will be returned here as an array
policies_matchedJSONIf 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_uidStringID of this authentication session, useful for continuous authentication
user_emailStringEmail address of the user that is authenticating
expires_atStringTimestamp 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#

FieldTypeDescription
response_codeStringError response code such as invalid_uid_secret or user_not_found
successBooleanfalse
statusStringStatus of the authentication request, always rejected for unsuccessful authentication requests
messageStringInformative 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#

MethodURL
POSTapi/v9/otp_verify
FieldTypeDescription
channelStringThe identifier for this authentication event, returned by authenticate_with_options
emailStringThe user's email
otpStringThe 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#

FieldTypeDescription
statusStringpending/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.
messageStringDescriptive 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#

FieldTypeDescription
response_codeStringError response code such as mfa_not_found or user_not_found
successBooleanfalse
statusStringStatus of the authentication request
messageStringInformative 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#

MethodURL
POSTapi/v9/check
FieldTypeDescription
channelStringThe identifier for this authentication event, returned by authenticate_with_options
emailStringEmail address of the user being authenticated by the relying party

Sample Request#

{  "channel": "xxx6910423f49963ade2d1951359b1fe15fcxxxxxxxx",  "email": "abe.lincoln@example.com"}

Response#

Successful Response#

FieldTypeDescription
channelStringAll further API calls related to this authentication request must utilize this channel.
statusStringStatus of an authentication request: approved/rejected/expired.
successBooleanAlways true for successful requests
auth_optionsArrayAllowed authentication methods for the MFA step
out_of_band_method_nameStringThe name of the method used for MFA
loa_scoreFloatLevel of assurance score returned from Acceptto Risk Engine: e.g. 2.5
meta_dataJSONMetadata available to eGuardian® for this authentication
eventStringAuthentication event, possible values: auth, post-auth
risk_analyzersJSONList of risk analyzers that participated in calculating the LOA score
policies_appliedJSONIf a policy applied to authentication request, name of policy will be returned here as an array
policies_matchedJSONIf a policy matched to authentication request, name of policy will be returned here as an array
session_uidStringID of this authentication session, useful for continuous authentication.
user_emailStringEmail address of the user that is authenticating
expires_atStringTimestamp 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#

FieldTypeDescription
response_codeStringError response code such as mfa_not_found or user_not_found
successBooleanfalse
statusStringStatus of the authentication request
messageStringInformative 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.

  1. 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.

  2. 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.

  3. 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#

MethodURL
POSTapi/v9/get_user_by_websocket_channel
FieldTypeDescription
websocket_channelStringThe channel generated by the javascript snippet above.
uidStringUnique ID of the relying party application that is performing the authentication
secretStringUnique 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#

FieldTypeDescription
successBooleantrue
messageStringBlank for successful requests
user_emailStringEmail address of the user who scanned the QR code on It'sMe.
user_idIntegereGuardian® 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#

FieldTypeDescription
response_code optionalStringError response code such as invalid_uid_secret
successBooleanfalse
user_emailStringBlank for unsuccessful requests
messageStringInformative 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#

MethodURL
POSTapi/v9/is_user_valid
FieldTypeDescription
emailStringThe email address of the user of the relying party which is being verified on eGuardian®.
uidStringUnique ID of the relying party application that is performing the authentication
secretStringUnique 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#

FieldTypeDescription
validBooleanTrue if the user and the application indicated by the UID and secret are both present on eGuardian®, False otherwise
registration_stateStringThe 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_pairedBooleanIndicates 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#

MethodURL
POSTapi/v10/risk_engine/calculate_score
FieldTypeDescription
uidStringUnique ID of the relying party application that is performing the authentication
secretStringUnique secret of the relying party application that is performing the authentication
emailStringUser's email address. Email domain should belong to the organization.
session_uidStringA 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.
eventStringThe authentication event, possible values are pre-auth, auth, post-auth, cont-auth (Continuous authentication).
contextJSONThe 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.

KeyDescriptionRisk Analyzer
ip_addressThe public IP address of the end-user.IP Risk Analyzer
latitudeThe 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
longitudeThe 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
accuracyThe 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
bfpTokenWhen 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_agentA 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_nameOut-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_uuidA universally unique mobile device identifier if the data is coming from a native mobile application.Device Trust
mobile_device.device_typeModel information of the mobile device. e.g. iPhone 11Device Trust
mobile_device.app_versionNative mobile application version number that is sending the information.Device Trust
mobile_device.os_typeMobile device operating system. e.g. iOS/AndroidDevice Trust
mobile_device.os_versionOperating system version of the mobile device. e.g. 14.5.1Device Trust
mobile_device.device_brandMaker of the mobile device. e.g. Apple/Samsung/Google/...Device Trust
mobile_device.ip_addressIP address of the mobile device.Device Trust
mobile_device.remote_ip_addressX-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.locationsList 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.latitudeThe 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.longitudeThe 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_dateThe 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#

FieldTypeDescription
successBooleantrue
loa_scoreFloatLOA score calculated by the risk engine based on the parameters provided in the request context.
messageStringBlank for successful requests
idIntegerInternal risk session ID
risk_analyzersArrayRisk 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#

FieldTypeDescription
successBooleanAlways false for unsuccessful requests
loa_scoreInteger0 for unsuccessful requests
messageStringInformative 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.