Skip to main content
Code42 Support

Access Lock

Available in:

StandardPremiumEnterprise
Small Business
Applies to:

Overview

Access Lock enables administrators to lock a user device. This prevents access to all content on the device (not just the files selected for backup). Access Lock leverages Microsoft's BitLocker technology to lock all drives connected to the device with a new key. Once a device is locked, it is completely inaccessible without the new recovery key to unlock it.

Access Lock is very useful to prevent unauthorized access if:

  • A user is identified as an insider threat
  • A device is lost or stolen

Considerations

  • Locking a device is a potentially destructive action. Exercise caution when following the steps in this tutorial.
  • Access Lock is only supported on Windows devices with BitLocker already enabled.
  • Access Lock requires Code42 app version 6.0 or later.
  • In Code42 environments with an on-premises authority server, using Access Lock requires SYSADMIN permissions. In Code42 cloud environments, Access Lock requires Customer Cloud Admin permissions.
  • If a user attempts to adopt a locked device before the administrator unlocks it, the replacement device also immediately locks itself. Therefore, if replacing a lost or stolen device, users should treat the replacement as a new device and restore the files without also assuming the old device's backup settings.
  • Locking a device that is part of an Active Directory (AD) domain may fail if the device cannot access the domain. In environments that use Group Policy Objects (GPO) to manage Windows devices, there is a BitLocker group policy that defines whether users can lock their own devices.
    • If the device is not connected to the domain (off the corporate network) and that policy is disabled, Access Lock does not have authority to lock the device.
    • If the device is connected to the domain (on the corporate network), Access Lock can lock the device regardless of the BitLocker group policy setting.

Before you begin

Identify the deviceGuid of the device you want to lock or unlock:

  1. Sign in to the administration console.
  2. Select Devices.
  3. Locate and select the device you want to lock or unlock.
    The device details appear.
  4. Note the 18-digit number at the top of the screen, directly below the device name. This is the deviceGuid and is required to complete the steps below.

Access lock API resource details

Access Lock functionality requires sending commands to the Code42 API. Use whatever API tool you choose.

Summary

  • Resource name (case sensitive): AccessLock
  • Required values
    • Authorization (requires both a session cookie and a Code42 administrator account):
      • Your Code42 administrator username and password.
      • Session cookie obtained with the auth/jwt resource, or with the Interceptor browser plugin (see details below).
    • Code42 server protocol, host and port: For example, https://authority-server.example.com:4285
    • deviceGuid: The GUID of the device to be locked or unlocked. This is a path parameter, not a query parameter. For example:
https://authority-server.example.com:4285/c42api/v3/AccessLock/1234567891234567

Methods

  • POST: Locks access to a device. This renders the device completely inoperable.
  • PATCH: Unlocks access to a device. This flags the device as unlocked in the Code42 server and returns the lockPassphrase required to unlock the device. The lockPassphrase must be manually entered on the physical device to complete the unlock process. The PATCH response also includes all the information listed below in the GET response.
  • GET: Returns the following status information about a device:
    • lockingUserUid: The userUID of the user who locked the device (if applicable).
    • unlockingUserUid: The userUID of the user who unlocked the device (if applicable).
    • isLockEnabled: "true" indicates the device is locked. "false" indicates it is unlocked.
    • lockEnabledDate: The date and time the device was locked (if applicable).
    • unlockDate: The date and time the device was unlocked (if applicable).
    • lockPassphrase: The passphrase used to lock volumes on the device. Use this passphrase to unlock the device.
    • lockedVolumeCount: The total number of locked volumes (drives) connected to the device.
    • totalVolumeCount: The total number of volumes (drives) connected to the device.
    • isOsVolumeLocked: "true" indicates the operating system volume is locked. "false" indicates it is not locked.
    • lastClientResponseDate: The date and time the Code42 server last received an update from the device. Note that locked devices are not able to communicate with the Code42 server.
    • modificationDate: The date and time any Access Lock settings for this device were modified.
    • creationDate: The date and time Access Lock was initiated.

Use access lock with curl and the Code42 API

The steps below assume basic familiarity with cURL commands.

Authentication

Authentication requires both a Code42 administrator account and a session cookie.

To obtain the session cookie, use the auth/jwt resource with your Code42 administrator credentials. In the example below, replace username and password with your credentials. Send the request to your Code42 server's domain name and API port (the default port is 4285). You must use the https protocol. For example:

curl -X GET -vv --insecure -u username:password https://authority-server.example.com:4285/c42api/v3/auth/jwt

The Code42 API returns a response:

*   Trying authority-server.example.com...
* Connected to authority-server.example.com port 4285 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* Server certificate: Unknown
* Server auth using Basic with user 'username'
> GET /c42api/v3/auth/jwt HTTP/1.1
> Host: authority-server.example.com
> Authorization: Basic YWRtaW46YWRtaW4=
> User-Agent: curl/7.49.1
> Accept: */*
> 
< HTTP/1.1 200 OK
< Date: Sat, 03 Dec 2016 16:40:50 GMT
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN
< Set-Cookie: C42_JWT_API_TOKEN=eyJjdHkiOiJKV1QiLCJlbmMiOiJBMTI4R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.mP3OXIY6X8WUgeXty2xj4t72c2hVbAKiRdUwU9keI0zdvwOr422tuePI0IGBJElwmnwDbfSiR1Ac9Q9DOZH5u6i-PSdG_7PGy69B6D-rQfopRngZK0swcHabPfBIW2yLrRgwGbDAAXiOMkpdYFJpYVkI_sJ_MeReSoYckMZ2uqi1GJ3d1f9j5gyFCbjEvNZVlKmoRJ52QsoCEm18fkGZixBsDG77oC6D4epmpYkztfD6SuAYaR0lUuWIfzOcJ-VGvNOWh_pZQH1s9ZH5-zLtwPuRAPmdNgmp0XJ7Iw1b5kcb0JXL6i5GzjNE0Ib-6g67Gbaj_D9Fd963sNmaRpkRbQ.ym5QZIqtKwTY1SHV.9CtJFEtGURuC_c0bcuFxG9UrerEe3anfAWO16yXHdy9Lr2XNHU5lJQ5hyOwfXZMPOchLx5h-OT4kFWqugIvsboV7HeWbMeli7-ABowEIWMabLfm5L3jIMmBmrB7VK5ms-ifmHNXrIcuHiGwdBU0ULIi3HcTcXOgME-nnsQXB2IsqxUS5xYh-LNmacXPdoL-kO4DLIc6m9GV-fGDGSyIXLoylFu09fUTffOFaU3mq9jEOjkrtM12WsfkqB0wLA-Eoae7PY_qmL9oDTxUoxMfci_zdP5OsiWnSjoP_-teeQ2tz-32iNaBN-eZ-KurPYGVWAzCGFiZHzh5IhUJBV8DwU6322aackmFQuk6ipDYZ8ITEQHnqXKmcsCQmA-V6odNEPJONMsZiU1N8KKSApkZF7zX5t1PrbJ3Ti2J4qPysuE3ZG_f245CA_Mk-DsovEd2IPnsDk6C9J5eQWlen5la6ZzLrM1ljSkKMK01D0OzTPSshts4Ge124kXaTYEvd5vtQoRjLYQ94k1dYbnpDyG0x4J9uU2P2dffMzRWih5V8bSwXxHQ2e71BF3BMC4eGP4xucNt-PoywpHUqld8ZeD44FkjBC9Mlf87V_cdC7jEOPK1H_ea_34nAurkuri6l__CZjICbA1ahURTv-K9GVs0SrcpnbJfuEO8RFf4YlN0XTaoZCj0bY5h8gsRvBifYGSjBePsM9lkoQzwiX4EnYpwQj2K64slCSA.AyQ-MC1hyzmWE_YF55j0tQ;Version=1;Path=/c42api;Max-Age=43200;Secure;HttpOnly
< Content-Length: 0
< 
* Connection #0 to host authority-server.example.com left intact

The session cookie begins after Set-Cookie: C42_JWT_API_TOKEN= and continues until ;Version=1. In the above example, it is eyJjdHkiO..._YF55j0tQ

Copy this cookie to the clipboard or a plain text file. You must include it in future requests.

Lock a device (post)

Locking a device uses Microsoft's BitLocker technology to lock all volumes (drives) connected to the device by deleting all existing keys and replacing them with a new recovery key generated by the Code42 server. When a device receives the lock command, it immediately restarts itself and boots to the BitLocker recovery screen. All data on the volumes are encrypted, rendering the device inoperable and inaccessible without the new recovery key. Only an administrator can retrieve the new recovery key (see Unlocking A Device below).

If the device is offline when the lock command is issued, it will lock itself the next time it comes online and connects to the Code42 server.

Steps

To lock access to a device, use the POST method of the AccessLock resource.

  1. Add the deviceGuid of the device to be locked as the path parameter. In the example below, the deviceGuid is 1234567891234567.
  2. Include the session cookie obtained above. To improve readability, this example includes only a small excerpt of the cookie; your actual cookie will be much longer. For example:
curl -X POST --insecure --header 'Content-Type: application/json' --header 'Accept: application/json' --cookie "C42_JWT_API_TOKEN=eyJjdHkiOiJKV1QiLCJlbm" https://authority-server.example.com:4285/c42api/v3/AccessLock/1234567891234567

The Code42 API response indicates the status of the device. Possible responses include:

Response Code Description
200 The device received the lock message.
202 The Code42 server could not connect to the device. However, the device is flagged to be locked and will lock its volumes the next time it connects to the Code42 server.
204 The specified device is already locked.
400 Invalid deviceGuid.
403 User not authorized to lock the specified device.
404 Bad URI, or missing resource.

Unlock a device (patch)

To unlock a device and restore access, use the PATCH method of the AccessLock resource, then enter the returned key on the device.

  1. Add the deviceGuid of the device to be unlocked as the path parameter. In the example below, the deviceGuid is 1234567891234567.
  2. Include the session cookie obtained above. To improve readability, this example includes only a small excerpt of the cookie; your actual cookie will be much longer.
curl -X PATCH --insecure --header 'Content-Type: application/json' --header 'Accept: application/json' --cookie "C42_JWT_API_TOKEN=eyJjdHkiOiJKV1QiLCJlbm" https://authority-server.example.com:4285/c42api/v3/AccessLock/1234567891234567
  1. Review the results and locate the lockPassphrase (see sample response below). This is the BitLocker recovery key necessary to unlock the device. Copy and save this value!
  2. Enter the recovery key on the locked device.
Save the lockpassphrase
If you lock the device again (by submitting another POST request) before entering the lockPassphrase on the locked device, a new passphrase is created on the Code42 server, but the device is still locked with the original lockPassphrase.

If you don't save the lockPassphrase returned the first time the PATCH method is called, you will not be able to recover the correct passphrase and therefore will not be able to unlock the device.
Sample Response
{
  "data": {
    "deviceGuid": "1234567891234567",
    "lockingUserUid": "thwlhuOyiq2svbdcqfmm2demndi",
    "unlockingUserUid": "thwlhuOyiq2svbdcqfmm2demndi",
    "isLockEnabled": false,
    "lockEnabledDate": "2016-12-02T20:29:29.442+0000",
    "unlockDate": "2016-12-02T21:20:28.149+0000",
    "lockPassphrase": "123805-583902-601854-267817-424677-239437-457204-498487",
    "lockedVolumeCount": null,
    "totalVolumeCount": null,
    "isOsVolumeLocked": false,
    "lastClientResponseDate": null,
    "modificationDate": "2016-12-02T21:20:28.149+0000",
    "creationDate": "2016-12-02T20:29:29.442+0000"
  },
  "error": null
}

Check the status of a device (get)

To view the status of a device, use the GET method of the AccessLock resource.

  1. Add the deviceGuid of the device to be unlocked as the path parameter. In the example below, the deviceGuid is 1234567891234567.
  2. Include the session cookie obtained above. To improve readability, this example includes only a small excerpt of the cookie; your actual cookie will be much longer.
curl -X GET --insecure --header 'Content-Type: application/json' --header 'Accept: application/json' --cookie "C42_JWT_API_TOKEN=eyJjdHkiOiJKV1QiLCJlbm" https://authority-server.example.com:4285/c42api/v3/AccessLock/1234567891234567
  1. Review the results. A detailed description of all response values is provided above in the Methods section.
Use patch to unlock
To unlock a device, you must use the PATCH method. If you obtain the lockPassphrase using the GET method and then enter the passphrase on the device, the device will relock itself as soon as it connects to the Code42 server because the device is still flagged to be locked.

Example: Use Postman to interact with the Code42 API

If you do not have a preferred method for accessing the Code42 API, consider using Postman, an app for the Chrome web browser designed to simplify interactions with APIs. Postman works on any operating system with a web browser and does not require specialized programming or scripting experience.

Because the AccessLock API resource requires a session cookie as part of the authentication, the Interceptor plugin is also required if you choose to use Postman.

The steps below illustrate how to use Postman to access the Code42 API, but are intended only as an example of one method for using Access Lock.

Before you begin

  1. Install the Chrome app Postman.
  2. Install the Chrome browser extension Interceptor.
  3. Open a Chrome browser window and sign in to the Code42 administration console with administrator credentials. This browser session serves to properly authenticate the administrator and is required to complete the steps below.

Steps

From Postman:

  1. Enable Interceptor.
  2. Select POST, PATCH, or GET.
    • POST locks a device
    • PATCH unlocks a device
    • GET returns status information for a device
  3. In Enter request URL:
    • Enter your authority server's protocol, host, and port, followed by /c42api/v3/AccessLock.
      You must use the https protocol.
    • Append the deviceGuid of the target device as a path parameter. In the example below, the deviceGuid is 1234567891234567:
https://authority-server.example.com:4285/c42api/v3/AccessLock/1234567891234567
  1. Select Authorization > No Auth. Authentication is handled by the Chrome web browser's signed-in session to the administration console.
  2. Select Send.
  3. Review the response. Postman displays the same response from the Code42 API as a cURL command. For more details about interpreting each response, see the POST, PATCH, and GET sections above.

Using Postman to interact with the Access Lock API

External resources

  • Was this article helpful?