Using resource-level access control

With resource-level access control, you can control user and API key access to manage devices. You use resource groups to specify the devices in an organization that each user or API key can manage.

For more information on how to configure resource-level access control, see Configuring resource-level access control.

Resource-level access control concepts

Device groups are part of the resource-level access controls for the IoT tool. You can use the device groups feature to manage the number of devices that personnel can access according to their role. Before you implement device groups, determine and record the intent and scope of the device groups to increase the efficiency of your solution.

You can implement device groups as part of your IoT solution to enable a user or application to access a subset of devices rather than all devices that are associated with an organization. To increase the efficiency of device groups, use device groups when one person must have access to many devices.

For example, a company that employs a number of field engineers and operations personnel wants to implement an IoT solution across the United Kingdom. The company configures a device group for each of the 69 cities, 9 device groups for each of the geographical regions, and a device group for the whole of the United Kingdom. Devices are allocated to these groups, and the groups are assigned to 15 field engineers and operations personnel, some of whom have access to more than one group. Users that are responsible for just one or two devices can continue to use mobile applications and enterprise architectures that are external to the IoT tool but compliment the overall IoT solution.

Resource group limits for access control

Resource group limits are enforced to ensure that the resource-level access control feature works effectively. The limits restrict the number of resource groups that are assigned to a subject, the number of devices within the groups, and the number of groups that a resource can belong to.

The following limits are enforced:

A maximum of 10 resource groups can be assigned to an API key, user, or gateway.
A resource group can have a maximum of 300 resources.
A resource can belong to a maximum of 10 groups.

Resource-level access control terminology

You can use the following sections to help you to understand the terminology that is used in the resource-level access control feature.

Subjects

A subject is an authenticated device that requests platform access, which must be authorized. The following types of subjects are valid:

Users: The people that use the applications. A member is a user whose account has no expiration date, and a guest is a user whose account has an expiration date.
Devices: Physical devices that access the IoT tool and use the type Device.
Gateways: Physical devices that access the IoT tool and use the type Gateway.
Applications: Applications or services that access the IoT tool by using API keys for authorization and access control.

Resources

A resource is a device that the subject performs the action on. The subject requests authorized platform access for the resource.

Actions

The action is what the subject performs, which most often is Create, Read, Update, Delete, or Execute. Operations are used to group actions on resources.

Applications

An application can act on behalf of a subject that is unknown to the tool, such as a mobile application that controls a domestic appliance, and an application can act on behalf of a real or simulated device that is known or unknown to the tool. An application can also be a true server-side application that is not acting on behalf of any other device.

Authentication is provided by and access to the IoT tool is given based on an API key or token.

Operations

An operation contains one or more actions that are run on a certain resource type by using user interfaces and programmatic interfaces, such as REST services and MQTT interfaces. They are used by different subjects such as members, applications, and devices. Operations are identified by their Operation IDs (OID).

Roles

Roles are sets of operations that are used to provide permission to use the operations. A subject can have multiple roles, and the role is an attribute of a subject.

Roles format

Array of 0..n roles

    { "roles": [ "PD_ADMIN_APP" ] }

Roles To Groups format

Map of 0..n <string, list <string> pairs</string>

    { "rolesToGroups": { "PD_ADMIN_APP": [ "group1" ] } }

Permissions

Permissions allow a subject to run operations on a resource or resource group.

Resource groups

A resource group is a collection of devices as resources. Devices can be added to resource groups and resource groups can be assigned to subjects in role-to-groups pairs. These relationships allow the subjects to perform operations for a role on specific groups of devices.

Users

Users log in to the IoT tool dashboard by using an ID that is a member of an organization. Users are assigned roles that grant them authorization to call certain sets of HTTP APIs. For more information about user roles, see User roles

API keys

API keys are tokens that are used to call the IoT tool HTTP APIs. API keys are assigned roles that grant them authorization to call certain sets of HTTP APIs. For more information about API key roles, see Application roles.

APIs where resource-level access control is enforced

When resource-level access control is enabled, the following device-related APIs only work if the specified device is accessible to the caller.

Device APIs (individual)

List devices of type

Only the subset of devices that belong to the appropriate groups is returned.

    GET /api/v0002/device/types/${typeId}

Get device

Returns a 404 error if the device is not accessible by the caller.

    GET /api/v0002/device/types/${typeId}/devices/${deviceId}

Get device management details

Returns a 404 error if the device is not accessible by the caller.

    GET /api/v0002/device/types/${typeId}/devices/${deviceId}/mgmt

Get devices registered by a gateway

Returns a 404 error if the gateway is not accessible by the caller. Only the subset of devices that belong to the appropriate groups is returned. The devices and the gateways must be in the group of the caller.

    GET /api/v0002/device/types/${typeId}/devices/${gatewayId}/devices

Update device

Returns a 404 error if the device is not accessible by the caller.

    PUT /api/v0002/device/types/${typeId}/devices/${deviceId}

Delete device

Returns a 404 error if the device is not accessible by the caller.

    DELETE /api/v0002/device/types/${typeId}/devices/${deviceId}

Device APIs (bulk)

List devices

Only the subset of devices that belong to the appropriate groups is returned.

    GET /api/v0002/bulk/devices

Delete devices

Only the subset of devices that belong to the appropriate groups is deleted. Devices that are not accessible still return with success = true.

    DELETE /api/v0002/bulk/devices/remove

Update devices

    PUT /api/v0002/bulk/devices/update

Device Management APIs

Initiate request

Fails if any device is not accessible to the caller.

    POST /api/v0002/mgmt/requests

Delete request

Fails if any device is not accessible to the caller.

    DELETE /api/v0002/mgmt/requests/${requestId}

View request

    GET /api/v0002/mgmt/requests/${requestId}

List requests

    GET /api/v0002/mgmt/requests

Get one request

    GET /api/v0002/mgmt/requests/${requestId}

Get request device details

    GET /api/v0002/mgmt/requests/${requestId}/deviceStatus

Get request device details for one device

    GET /api/v0002/mgmt/requests/${requestId}/deviceStatus/${typeId}/${deviceId}

Problem Determination APIs

Connection logs for a device

Returns an empty array if the device is not accessible.

    GET /api/v0002/logs/connection

Add device error code

Returns a 404 error if the device is not accessible by the caller.

    POST /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/errorCodes

List device error codes

Returns a 404 error if the device is not accessible by the caller.

    GET /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/errorCodes

Clear device error codes

Returns a 404 error if the device is not accessible by the caller.

    DELETE /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/errorCodes

Add device diagnostic log

Returns a 404 error if the device is not accessible by the caller.

    POST /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/logs

Add device diagnostic log

Returns a 404 error if the device is not accessible by the caller.

    POST /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/logs

List device diagnostic log

Returns a 404 error if the device is not accessible by the caller.

    GET /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/logs

List device diagnostic log

Returns a 404 error if the device is not accessible by the caller.

    GET /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/logs

Get one device diagnostic log

Returns a 404 error if the device is not accessible by the caller.

    GET /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/logs/${logId}

Clear device diagnostic log

Returns a 404 error if the device is not accessible by the caller.

    DELETE /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/logs

Clear device diagnostic log

Returns a 404 error if the device is not accessible by the caller.

    DELETE /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/logs

Delete one device diagnostic log

Returns a 404 error if the device is not accessible by the caller.

    DELETE /api/v0002/device/types/${typeId}/devices/${deviceId}/diag/logs/${logId}

Last Event Cache APIs

Get events for the device

Returns a 404 error if the device is not accessible by the caller.

    GET /api/v0002/device/types/${typeId}/devices/${deviceId}/events

Get events for the device

Returns a 404 error if the device is not accessible by the caller.

    GET /api/v0002/device/types/${typeId}/devices/${deviceId}/events/${eventId}

Get logical interface for the device

Returns a 404 error if the device is not in the caller's group.

    GET /api/v0002/device/types/{typeId}/devices/{deviceId}/state/{logicalInterfaceId}