Device Management Tool for Admins

Important: This guide is intended for a Device Management Tool that will be used by your internal administrators and support teams. If you want to build a Device Management Tool that will be displayed and used by your end users, please follow the guide for building a User Devices List.

Note: This chapter assumes that you have completed the Baseline, Account Recovery, and Engaging Your Users integrations.

Intro to Device Management Tool

In order to more efficiently support your users, your support teams at times may need to forcibly approve or report a device. Approving a device on a user's account will peg that device's risk score to 0, marking it as a trusted device, and ensuring your can access their account with that device without and challenges or denials. Reporting a device on a user's account will peg that device's risk score to 100, and will trigger an $incident.confirmed webhook on that users account. Assuming you have already completed the Baseline and Account Recovery integrations, reporting a device this ensures it will be denied access to the user's account and the user will be notified and directed to reset their password.

User Devices Landing Page

With the follow steps, you'll be able to build out a landing page where an administrator can review all of the devices accessing a specified user's account, and they can approve or report any device. By the end of this step, here is an example of a Device Managemtn Page you'll be able to create for your administrators and support teams: User Devices landing page

User Devices API

In order to fetch a list of devices accessing a user's account, call Castle's /users endpoint as such:

Example Request

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

Sample Response - User Devices Endpoint

{
  "total_count": 2,
  "data": [
    {
      "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6IkZSWHZnc3pvRWNHejNXYzVic1pjUHBjV3NzRXF1NDhqIiwidmVyc2lvbiI6MC4xfQ.AI5m5rUf97KZQg4o0zITwhNtbdgiAN9C2p3soDTg4sQ",
      "risk": 0.000154,
      "created_at": "2018-06-15T16:36:22.916Z",
      "last_seen_at": "2018-07-19T23:09:29.681Z",
      "approved_at": null,
      "escalated_at": null,
      "mitigated_at": null,
      "context": {
        "ip": "74.102.236.7",
        "location": {
          "country_code": "US",
          "country": "United States",
          "region": "New Jersey",
          "region_code": "NJ",
          "city": "Lyndhurst",
          "lat": 40.7923,
          "lon": -74.1001 
        },
        "user_agent": {
          "raw": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.87 Safari/537.36 OPR/54.0.2952.51",
          "browser": "Opera",
          "version": "54.0.2952",
          "os": "Mac OS X 10.13.6",
          "mobile": false,
          "platform": "Mac OS X",
          "device": "Unknown",
          "family": "Opera"
        },
        "type": "desktop"
      }
    },
    {
      "token": "eyJhbGciOiJIUzJ1NiJ9.eyJ0b2tlbiI6InhDb0hmd3h6VlZlbWR0NEN0Wlk4eGhrc0pHeldnMjdFIiwidmVyc2lvbiI6MC4xfQ.8Ll1-hR-hDjIAO27DgllWllQP6u2XG_syZayU_6FG80",
      "risk": 0.560931,
      "created_at": "2018-06-05T20:54:12.416Z",
      "last_seen_at": "2018-06-05T20:54:12.416Z",
      "approved_at": null,
      "escalated_at": null,
      "mitigated_at": null,
      "context": {
        "ip": "193.106.230.209",
        "location": {
          "country_code": "US",
          "country": "United States",
          "region": "California",
          "region_code": "CA",
          "city": "Goleta",
          "lat": 34.5021,
          "lon": -120.1287
        },
        "user_agent": {
          "raw": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:60.0) Gecko/20100101 Firefox/60.0",
          "browser": "Firefox",
          "version": "60.0",
          "os": "Mac OS X 10.13",
          "mobile": false,
          "platform": "Mac OS X",
          "device": "Unknown",
          "family": "Firefox"
        },
        "type": "desktop"
      }
    }
  ]
}

With this, for each device you can highlight details on the screen to your administrators.

Additional pieces of UI you'll be able to include are Approve and Report buttons, allowing an admin to forcibly approve or report any given device respectively.

Approving a Device

If an admin clicks Approve, send a PUT request to Castle's devices endpoint as such:

curl https://api.castle.io/v1/devices/{device_token}/approve \
  -X PUT \
  -u ":YOUR-CASTLE-API-SECRET"

Important: By approving a device, you are confirming that this device was used by the account owner. The device's risk score will be pegged to 0 and it will be considered a safe device for this user. Only do this if you have confidently confirmed that this device is in use by the true account owner.

Reporting a Device

If an admin clicks Approve, send a PUT request to Castle's devices endpoint as such:

curl https://api.castle.io/v1/devices/{device_token}/report \
  -X PUT \
  -u ":YOUR-CASTLE-API-SECRET"

Important: By reporting a device you are confirming a compromise on this user's account and pegging the device to a risk score of 100. It will result in an $incident.confirmed event and webhook event being triggered for this user. Therefore, assuming you have already implemented Objective 2: Account Recovery, the Password Reset email will be automatically sent to this user. Also, assuming you have already implemented Objective 1: Protecting your Login, this device will be denied access to the user's account.