Receiving End User Feedback

Prerequisites

In order for end-user feedback to be meaningful, Castle must first be integrated with in-application endpoints where users have been authenticated.

If a user provides confirmation of unauthorized access to their account, then an automated account recovery workflow should already be in place. However, strictly speaking, the device feedback mechanisms described here do not have strict dependencies on the recommended prerequisites.


Introduction

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 a 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 the headaches of false-positives, user complaints, and cumbersome 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.

Note: If you are looking for a way to build an internal device management application, head to the Using the User Devices API Tutorial.


Steps

A quick note - the device_token (or token) should not be directly exposed to the user

Step 1. Design the review page

Step 1A. Create a mock design with available device properties

Here's an example of the data provided by Castle's /v1/users/{user_id}/devices endpoint:

{
    "total_count": 1,
    "data": [
        {
            "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6InJtemtGRkxSeWVNT1U5MGpIbUxqVlhOQmxsam8iLCJxdWFsaWZpZXIiOiJBUUlDQ2pFeE1EQXpOell6T1RBIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ.oIgZE1kzLojvj00VjSACeXmuv8TjQHNIGDygmnW9L1c",
            "created_at": "2021-01-27T21:34:53.697Z",
            "last_seen_at": "2021-01-27T21:34:53.281Z",
            "user_id": "80c43238-375f-4cbc-8bff-357d1c564cf5",
            "approved_at": null,
            "escalated_at": null,
            "mitigated_at": null,
            "context": {
                "ip": "172.56.39.210",
                "location": {
                  "street": null,
                  "city": "San Francsico",
                  "postal_code": 94107,
                  "region": "CA",
                  "country": "US",
                  "lon": -122.3870544,
                  "lat": 37.8019832
                },
                "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"
                },
                "properties": {},
                "type": "desktop"
            },
            "is_current_device": false
        }
    ]
}

Based on the properties above, a review landing page for a single device might look something like this:

An example prompt asking a user if they recognize the device detailsAn example prompt asking a user if they recognize the device details

An example prompt asking a user if they recognize the device details

Step 1B. (optional) Highlight or hide certain devices

If you call the /devices endpoint and populate the optional url parameter cid with a request token, Castle will analyze the request token to see if there is a match in our data. If there is a match, the matched device in the response will contain is_current_device=true.

Additionally, devices will contain the approved_at timestamp if they have been approved in the past. Devices are approved under a few conditions:

  1. Castle Dashboard (Admin) Feedback
  2. $registration Risk event
  3. $challenge.succeeded Track event
  4. user.registered_at < 60 minutes ago (devices used to register accounts are automatically approved)

Highlighting the user's current device or approved devices (or hiding them from view) may be useful to ensure the user does not accidentally revoke access to these devices.

Step 1C. Display review page to users

Depending on your Castle Policies and risk model, you may only want to provide users the ability to "revoke" devices from their account. If you do choose to allow users to "approve" devices, we recommend that you thoroughly authenticate the user before allowing this action to take place.

Step 2. Proxy user feedback to Castle

As stated at the top of this tutorial, the device_token should not be directly exposed to the user. The reason is that the device_token does not expire, and it may be used to alter the risk score for that device.

Revoke access for a device

  1. If the user clicks "No, it wasn’t me", prompt the user with a confirmation dialogue to ensure they want to report this device.

  2. Track a $review.escalated event to Castle from the backend:

curl --location --request POST 'https://api.castle.io/v1/track' \
--header 'Authorization: Basic xxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "event": "$review.escalated",
  "device_token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6InJtemJfT3pSOWd1d1UtTExvR0xXRERWQnFiQlciLCJxdWFsaWZpZXIiOiJBUUlDQ2pFeE1ERTJNamM0T1RZIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ.yWZrupKVJPrh2cxWfkVDdCik9vG--DPzJk5iQwJhGI4"
}'
  1. 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 completed Tutorial: Automate Account Recovery, the Password Reset email will be automatically sent to this user.

Approve a device

Depending on your Policies, the action of approving a device may allow a user to avoid future MFA challenges when they are using that device. Based on your risk models and user experience desires, you should decide what level of user authentication you want to implement when a user desires to approve a device. Castle will accept the device_token for approval regardless of that device history or the current state of user authentication.

  1. If the user clicks "Yes, this was me", prompt the user with a confirmation dialogue to ensure they want to confirm the approval.

  2. Once the user has confirmed the login, track a $challenge.succeeded event from your backend, including the device_token​:

curl --location --request POST 'https://api.castle.io/v1/track' \
--header 'Authorization: Basic xxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "event": "$challenge.succeeded",
  "device_token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6InJtemJfT3pSOWd1d1UtTExvR0xXRERWQnFiQlciLCJxdWFsaWZpZXIiOiJBUUlDQ2pFeE1ERTJNamM0T1RZIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ.yWZrupKVJPrh2cxWfkVDdCik9vG--DPzJk5iQwJhGI4"
}'
  1. Display a prompt informing the user that this device has been approved, and no further action is needed