Device Attributes API

1. Introduction

The Device Attributes API allows device administrators to allow certain origins to access certain attributes of the device running the UA. Unlike [MANAGED-CONFIG], which allows the device administrator to pass a custom JSON object to each origin, this API expects to pass the same set of values to all origins that the administrator has enabled.

2. Model

2.1. Managed devices

The API is presumed to be used on devices which are not fully controlled by the end user, but rather by an external entity, device administrator. Device administrators are given the power to fully control the managed devices.

2.2. Managed web applications

The API is presumed to be used by web applications, which are understood and managed by the device administrators.

2.3. Permission control

Most operating systems have a mechanism for the deployment of policies which can be used to configure many aspects of a device’s operating system or applications such as the web browser. This specification requires that permission to access these device attributes is configured through such a system. These policies are controlled by device administrators. They may not necessarily have the device user’s best interests.

Taking Chrome browser as an example, the status of managed web application is given to the origins which correspond to web applications selected by device administrators in the Google Admin Console and are automatically installed on the enterprise managed devices. For a managed web applications, permission to access these device attributes can be revoked if the device administrator doesn’t want to provide a specific application access.

2.4. Device attributes

The API is presumed to be used with a management infrastructure which allows device administrators to manage a fleet of devices and configure properties for those devices.

2.4.1. Annotated Asset ID

An administrator-defined value which uniquely identifies a device within an organization.

2.4.2. Annotated Location

An administrator-defined value which uniquely identifies a location within an organization.

2.4.3. Directory ID

An inventory management system-defined value which uniquely identifies a device within an organization.

2.4.4. Hostname

An administrator-defined value which is used as the device hostname during DHCP requests.

2.4.5. Serial Number

A manufacturer-defined value which uniquely identifies a device among those produced by that manufacturer.

3. NavigatorManagedData interface

[
  SecureContext,
  Exposed=Window
] interface NavigatorManagedData : EventTarget {
  // Device Attributes API.
  Promise<DOMString> getAnnotatedAssetId();
  Promise<DOMString> getAnnotatedLocation();
  Promise<DOMString> getDirectoryId();
  Promise<DOMString> getHostname();
  Promise<DOMString> getSerialNumber();
};

Methods on this interface typically complete asynchronously, queuing work on the managed data task source.

3.1. getAnnotatedAssetId() method

The getAnnotatedAssetId() method steps are:

1. Let promise be a new promise.

2. Run the following steps in parallel:

   1. If this API is not called by a managed web application with permission to access device attributes, queue a global task on the relevant global object of this using the managed data task source to reject promise with a "NotAllowedError" DOMException and abort these steps.

   2. Let annotatedAssetId be the annotated asset id set by the device administrator, or undefined if one has not been set.

   3. Queue a global task on the relevant global object of this using the managed data task source to resolve promise with annotatedAssetId.

3. Return promise.

3.2. getAnnotatedLocation() method

The getAnnotatedLocation() method steps are:

1. Let promise be a new promise.

2. Run the following steps in parallel:

   1. If this API is not called by a managed web application with permission to access device attributes, queue a global task on the relevant global object of this using the managed data task source to reject promise with a "NotAllowedError" DOMException and abort these steps.

   2. Let annotatedLocation be the annotated location set by the device administrator, or undefined if one has not been set.

   3. Queue a global task on the relevant global object of this using the managed data task source to resolve promise with annotatedLocation.

3. Return promise.

3.3. getDirectoryId() method

The getDirectoryId() method steps are:

1. Let promise be a new promise.

2. Run the following steps in parallel:

   1. If this API is not called by a managed web application with permission to access device attributes, queue a global task on the relevant global object of this using the managed data task source to reject promise with a "NotAllowedError" DOMException and abort these steps.

   2. Let directoryId be the directory id, or undefined if one is not provided by the management infrastructure.

   3. Queue a global task on the relevant global object of this using the managed data task source to resolve promise with directoryId.

3. Return promise.

3.4. getHostname() method

The getHostname() method steps are:

1. Let promise be a new promise.

2. Run the following steps in parallel:

   1. If this API is not called by a managed web application with permission to access device attributes, queue a global task on the relevant global object of this using the managed data task source to reject promise with a "NotAllowedError" DOMException and abort these steps.

   2. Let hostname be the hostname set by the device administrator, or undefined if one has not been set.

   3. Queue a global task on the relevant global object of this using the managed data task source to resolve promise with hostname.

3. Return promise.

3.5. getSerialNumber() method

The getSerialNumber() method steps are:

1. Let promise be a new promise.

2. Run the following steps in parallel:

   1. If this API is not called by a managed web application with permission to access device attributes, queue a global task on the relevant global object of this using the managed data task source to reject promise with a "NotAllowedError" DOMException and abort these steps.

   2. Let serialNumber be the serial number, or undefined if it is not available.

   3. Queue a global task on the relevant global object of this using the managed data task source to resolve promise with serialNumber.

3. Return promise.

4. Code example

Assuming there is a retail enterprise that relies on an online sales system. The backend service pushes different tariffs to the in-store devices based on their annotated location (country, city or sales region) in the morning, and collects sales reports in the afternoon.

With the help of Device Attributes API, this sales application can get the device location by using getAnnotatedLocation() method. The operation will fail if the API call is triggered by a phishing application - looks similar but not the expected one.

// Request sensitive data if the current environment is valid.
function successCallback(location) {
  const tariff = backend.requestTariff(location);
  console.log(tariff);
}
 
// Stop the workflow if the current environment is unexpected.
function failureCallback(error) {
  backend.reportFailure(error);
  console.error(error.message);
}
 
function PrepareTariff() {
  navigator.managed.getAnnotatedLocation()
                   .then(successCallback, failureCallback);
}

It is easy to write another similar code snippet to report the sales data including a device serial number by using getAnnotatedAssetId() method.

NOTE: The website should assume that the data could be tampered with, stolen or reused on another managed device. Alternative security measures should be put in place by the website itself.

function ReportSalesData() {
  navigator.managed.getAnnotatedAssetId.then(reportCallback);
}

5. Security considerations

In accordance with modern security practices, the permission of using these methods is controlled by the device administrator per origin. In addition, they are only available to secure contexts on the managed devices.

6. Privacy considerations

This API provides access to device attributes which will be the same for all origins. (See [MANAGED-CONFIG] for per-origin configuration of managed sites.) This could easily be used for tracking purposes if exposed arbitrarily. In a managed environment however, where an device administrator is configuring a fleet of machines for particular employees or tasks, it is desirable for these machines to be able to identify themselves to the sites they are expected to be accessing.

It is a non-goal for this interface to be used on unmanaged devices. End users are never asked to provide this information to a site. The decision of which origins are granted permission to access these device attributes is made by an authorized administrator of the organization to which they belong.

To prevent unnecessary information exposure the configuration mechanism requires the device administrator to grant access to these attributes to a limited set of origins, as granting access to all origins would create a mechanism for pervasive tracking of all web browsing on the device. Origins that are granted access are additionally secure contexts so that passive network attackers are unable to observe these attributes in transit.

NOTE: [RFC7258] treats pervasive monitoring as an attack, but it doesn’t apply to managed devices. In such cases, the actual owner of managed devices is not the end user but the device administrator who is expected to protect all end users by using proper permissions.