Engaging Your Users

This chapter assumes that you have completed the Baseline and Account Recovery integrations.

Intro to User Review Automation

In order to build trust with your users over time -- and to minimize manual support overhead -- it is best to proactively give your users a way to review abnormal activity on their accounts so that they can report and resolve incidents on their own. This section of the guide is for building a "Device Review" landing page on your website where a user can review activity from an unusual device that has accessed their account. With this, users can provide feedback on wider range of suspicious activity where a malicious incident hasn't necessarily taken place.

With a review page readily available, you can direct users here whenever moderately suspicious activity occurs on their account. By letting users have the final say in what activity and devices should be approved versus reported, it ensures you can implement a high degree of security without they headaches of false-positives, user complaints, and combersome support tickets.

What is considered "Suspicious"? There is a wide range of scenarios where "suspicious" activity is detected. Often it might not be an incident at all. For example, a user could be on vacation and browsing from a new device and geo, or browsing from a VPN. While these may be abnormal signals for a given user, there is not an exceedingly high degree of certainty that an "Incident" has occured. It would be premature and poor user experience to lock the users account in this scenario. Instead, it's a perfect time to notify the user that unusual activity was detected and ask them to review their activity.

Step 1. Subscribe to Review Webhooks

To get started, head over to the webhook settings in the Castle Dashboard and subscribe to the $review.opened event. This event will be triggered whenever the risk of a device exceeds 60, and will only trigger once per device.

Here is an example of the payload delivered in an $review.opened webhook:

Note: The payloads from $review.opened and $incident.confirmed webhooks are nearly identical. The only difference is the type field.

Sample Payload - Review webhook

{
  "api_version": "v1",
  "app_id": "382395555537961",
  "type": "$review.opened",
  "created_at": "2018-06-01T19:38:28.483Z",
  "data": {
    "id": "test",
    "device_token": "eyJhbGciOiJI1NiJ9.eyJ0b2tlbiI6InRlc3QiLCJzaW9uIjowLjF9._-0l6TlDH7m78l19z1amMQ02m7s",
    "user_id": "2",
    "trigger": "$login.succeeded",
    "context": {
      "ip": "172.56.39.210",
      "isp": {
        "isp_name": "CastleNet",
        "isp_organization": "Castle"
      },
      "location": {
        "country_code": "US",
        "country": "United States",
        "region": "California",
        "region_code": "CA",
        "city": "San Francisco",
        "lat": 37.8019832,
        "lon": -122.3870544
      },
      "user_agent": {
        "raw": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko)",
        "browser": "Chrome",
        "version": "42.0.2311",
        "os": "Mac OS X 10.9.5",
        "mobile": false,
        "platform": "Mac OS X",
        "device": "Unknown",
        "family": "Chrome"
      }  
    }
  } 
}

Handling the Review Webhook

Whenever you receive a webhook, first check the type to determine if it is $review.opened. If it is, you will want to begin Device Review notification process.

Warning: This webhook is not confirming a breach, therefore, you should not lock the users account as you would in the case of a $incident.confirmed webhook.

In the wehbook's payload, locate the user_id and device_token within the data object. These will be key parameters needed for the following steps.

Step 2. Notify the User

Next, you should notify the user that an unusual device was detected, and encourage them to review the activity.

You can parse the data in the payload of the webhook in order to customize an email to your user. Here is an example of an email that you could send your user:

Sample Unusual Device Notification Email

Review email

Note: We recommend providing details about the device and location that triggered the incident. In the case that the activity was not triggered by them, this provides evidence to the account owner that there account may have been breached, and will further encourage them to take swift action in reviewing the activity.

In the email, there is a button provided to Review this activity. This link should point to a URL of your choice where you will handle the rendering of the review landing page we'll discuss in the next step.

As a query string parameter, include the device_token from the original $review.opened webbhook's payload. This will allow you to fetch information about the device later on.

For example, the URL behind Review this activity would be:

https://mysite.com/review-activity?device_token={device_token}

Step 3. Device Review Landing Page

In this step, you'll build out a landing page where a user can review a device that has triggered a $review.opened webhook, and handle user feedback so that they can approve or report the device. By the end of this step, here is an example of the review landing page you'll be able to create for your users: Review landing page

Get Device Details

In the email above, you provided the user with a link to this page that contained a device_token.

In order to fetch details about the unusual device and activity, call Castle's /devices endpoint and pass the device_token:

Example Request

curl https://api.castle.io/v1/devices/{device_token} \
  -X GET \
  -u ":YOUR-API-SECRET" \
  -H "Content-Type: application/json" \

Sample Response - Device Endpoint

{
  "token": "19a0g9Hn84vkNSvRG6F9qM4j",
  "object": "device",   
  "created_at": "2017-12-28T17:22:40.556Z",
  "last_seen_at": "2018-06-11T17:10:26.928Z",
  "approved_at": null,
  "escalated_at": "2018-06-12T17:10:26.928Z",
  "mitigated_at": null,
  "risk": 1.0,
  "context": {
    "type": "desktop",
    "ip": "162.12.41.13",
    "user_agent": {
      "raw": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko)",
      "browser": "Chrome",
      "version": "42.0.2311",
      "os": "Mac OS X 10.9.5",
      "mobile": false,
      "platform": "Mac OS X",
      "device": "Unknown",
      "family": "Chrome"
    },
    "location": {
      "street": null,
      "city": "San Francsico",
      "postal_code": 94107,
      "region": "CA",
      "country": "US",
      "lon": -122.3870544,
      "lat": 37.8019832
    }
  }
}

With this, you can highlight details on the screen to the user, similar to what you sent in the email.

The only additional pieces of UI you'll want to include are Yes, this was me and No, it wasn't me buttons, allowing the user to approve or escalate the device & activity respectively.

Approving a Device

If the user clicks Yes, this was me, track a $challenge.succeeded event to Castle from the backend.

  1. Prompt the user with a confirmation dialogue to ensure they want to confirm the login
  2. Once the user has confirmed the login, track a $challenge.succeeded event from your backend, including the device_token​
  3. Display a prompt informing the user that this device has been approved and no further action is needed
castle.track(
  event: '$challenge.succeeded',
  device_token: device_token
)
castle.track(
    {
        'event': '$challenge.succeeded',
        'device_token': device_token
    }
)
<?
Castle::track(
  array(
    'event' => '$challenge.succeeded',
    'device_token' => $device_token
  )
);
castle.track(
  "$challenge.succeeded",
  device_token
);
curl https://api.castle.io/v1/track \
  -X POST \
  -u ":YOUR-API-SECRET" \
  -H "Content-Type: application/json" \
  -d '
    {
      "event": "$challenge.succeeded",
      "device_token": "{device_token}",
      "context": {
        "client_id": "a97b492d-dcc3-4fc1-87d6-65682955afa5",
        "ip": "37.46.187.90",
        "headers": {
          "User-Agent": "Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko",
          "Accept": "text/html",
          "Accept-Language": "en-us,en;q=0.5"
        }
      }
    }'

Reporting a Device

If the user clicks No, it wasn't me, track a $review.escalated event to Castle from the backend.

  1. Prompt the user with a confirmation dialogue to ensure they want to report this device
  2. Once the user has confirmed the login, track a $review.escalated event from your backend, including the device_token​
  3. Display a prompt informing the user that this device has been reported, their account has been locked, and they should check for a Reset Password email.

Note: Tracking a $review.escalated event will trigger an $incident.confirmed webhook. Therefore, assuming you have already implemented Objective 2: Account Recovery, the Password Reset email will be automatically sent to this user.

castle.track(
  event: '$review.escalated',
  device_token: device_token
)
castle.track(
    {
        'event': '$review.escalated',
        'device_token': device_token
    }
)
<?
Castle::track(
  array(
    'event' => '$review.escalated',
    'device_token' => $device_token
  )
);
castle.track(
  "$review.escalated",
  device_token
);
curl https://api.castle.io/v1/track \
  -X POST \
  -u ":YOUR-API-SECRET" \
  -H "Content-Type: application/json" \
  -d '
    {
      "event": "$review.escalated",
      "device_token": "{device_token}",
      "context": {
        "client_id": "a97b492d-dcc3-4fc1-87d6-65682955afa5",
        "ip": "37.46.187.90",
        "headers": {
          "User-Agent": "Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko",
          "Accept": "text/html",
          "Accept-Language": "en-us,en;q=0.5"
        }
      }
    }'