Skip to main content

Previous User Authentication API

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 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® Device & Browser Fingerprint (DBFP) cookie, if in use; see MFA integration with device browser fingerprint 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.

  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

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.

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

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

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

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

Note

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 device browser fingerprint

Use the following steps to integrate MFA with DBFP.

  1. In the body element of your HTML page, add the jQuery library in a script element.

    For example, you can include jQuery from a CDN (Content Delivery Network) link in the body element like the following:

    <!-- jQuery library (served from Google) -->
<script src=“https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js”></script>;

  2. Below the jQuery library script, add the following DBFP JavaScript file script:

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

  3. Save your changes.

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 SecureAuth Corporation.

In this section: