Working with Capabilities and Tags

Capabilities are permissions required to perform actions to entities on the BlackBerry IoT Platform. Before any device can perform an action, it must be granted the capability to do so. In fact, capabilities are useful only in the context of device entities because devices are the only entities that can perform an action. In general, entities that you create within an organization should have default capabilities assigned to allow devices to perform a minimal set of actions. You can either assign system-defined capabilities or extend some of the existing capabilities for application-specific usage for your application code.

You can add a capability to a target entity, and give (grant) that capability to an organization, application, user, device, or tag entity. Targets can be organization, firehose, application, device, or tag entities. That grant allows a device to perform an action on the target. You might wonder: why would you grant a capability to a non-device entity if devices are the only entities that can perform an action? The answer is simple–to assign a capability to more than one device using capability inheritance. For example, you could grant a capability to an application entity. That grant permits devices of that application to inherit the capability that was granted to the application. If capability inheritance was not possible, you would need to assign that capability to each device. For more information about capability inheritance, see Use capability inheritance.

The following illustration shows when a device wants to perform an action, there's a check to determine whether it has the capability granted to it. If the device does, then the platform allows the action to occur. If the device doesn't have the capability, the device won't be able to perform the action.

Targets grant capabilities to other entities.

Capabilities can be granted or removed at any time with the effect being immediate. By default, granted capabilities don't expire, but they can be configured to expire on a specific date and time. Expiring capabilities are useful to grant a device temporary capability for specified time to perform an action on a target. For more information, see Assign capabilities.

As you can imagine, as the number of applications, users, and devices grow, the assignment of capabilities can be a challenging task. To simplify the management of capabilities on multiple entities that scales appropriately, you can use tags and associations. For more information, see Use tags to simplify permission management and Use associations to simplify permission management.

System-defined capabilities

The BlackBerry IoT Platform comes with predefined system capabilities. These capabilities are granular and allow the granted entity to perform specific actions on another target. You can secure your data stored in the cloud to fit your business rules using these capabilities.

The following system-defined capabilities are available:

General capabilities

These are capabilities that can be performed on any entity.

Name Description
cap.create Create a capability on an entity
cap.delete Delete a capability from an entity
cap.read Read a capability
search.data Perform a search on device data. You can further limit the search using categories or data objects. For more information, see Working with Data.
search.device Perform a search on device information.
search.file Perform a search on file metatdata.

Capabilities to perform actions on organization entities

These are capabilities that can be performed on organizations.

Name Description
organization.read Read an organization
organization.update Update an organization
organization.tag Allow the organization to be tagged
organization.untag Allow a tag to be removed from an organization

Capabilities to perform actions on application entities

These are capabilities that can be performed on an application. This includes ability to manage data-retention policies.

Name Description
app.create Create an application
app.delete Delete an application
app.read Read application metadata
app.update Update an application
app.read.by.org Read applications in an organization
app.read.keys Read the API Key and Secret for an application
app.update.keys Update the API Key and Secret for an application
app.tag Tag an application
app.untag Allow a tag to be removed from an application
data.retention.create Create a data retention rule
data.retention.delete Delete a data retention rule
data.retention.read Read data retention rule
data.retention.update Update data retention rule

Capabilities to perform actions on device entities

These capabilities that can be performed on devices. Included as part of the capabilities for a device are capabilities to manage file entities, messages, and data.

Name Description
device.create Create a device
device.delete Delete a device
device.read Read device metadata
device.update Update a device
device.list.by.user.and.app List all devices by user and application
device.read.by.user Read device associated to user
device.tag Allow the device to be tagged
device.untag Allow the tag to be removed from a device
data.create Create data associated with a device
data.read Read data associated with a device
data.delete Delete device data
file.create Create a file
file.delete Delete a file
file.read Read a file
file.update Update the file's metadata
message.create Create a message. Typically, you require a defined message type (i.e., message.create.[message type]_) with this capability

Capabilities to perform actions on firehose entities

These capabilities that can be performed on firehoses.

Name Description
firehose.attach Consume or read data from a firehose
firehose.create Create a firehose
firehose.delete Delete a firehose
firehose.list Read the list of firehoses available
firehose.read Read the parameters for a firehose
firehose.update Update the parameters for a firehose
firehose.subscription.create Add a subscription to the firehose
firehose.subscription.delete Delete a subscription from a firehose
firehose.subscription.list Read a list of subscriptions for a firehose
firehose.subscription.read Read the parameters of a subscription

Capabilities to perform actions on tag entities

The capabilities to manage and use tags.

Name Description
tag.create Create a tag
tag.delete Delete a tag
tag.grant Required to tag another entity using this tag
tag.read Read a tag
tag.read.tagged.entities Read tagged entities by tag
tag.update Update a tag

Capabilities to perform actions on user entities

The capabilities to manage user entities within an organization.

Name Description
user.read Read a user
user.read.profile Read the profile for a user
user.add.org Add a user to an organization
user.remove.org Remove a user from an organization
user.read.by.org Read users in organization
user.tag Allow the user to be tagged
user.untag Allow a tag to be removed from a user

Extended capabilities

You can extend some of the system-defined capabilities to create a custom capability that are application-specific. Extended capabilities (or custom capabilities) are useful for granting other devices the ability to read messages, read specific data stored on devices, or perform searches on data. You can extend these capabilities:

Extend data.read and search.data

To extend the data.read or search.data capabilities, you should know how the data is organized, the category the data belongs to, and the name of the standard (always called default).

For information about the categories and standards, see Data.

To extend the data.read or search.data capabilities, use the following notation:

'data.read.'  + standard name + '.' + name of the category + '.' + name of data object

The data objects are application-specific. The available data objects and fields within the the data object are based on what you define in your application code. Data objects can have multiple fields. You specify access to each data object by its name.

For example, if you could have the following data objects:

To grant the search capability to the car_location and car_fuel_level data objects, here's what the capabilities would look like:

search.data.default.state.car_location
search.data.default.state.car_fuel_level

To grant the read capability to the car_alarm data object, here's what the capability looks like:

data.read.default.alarm.car_alarm

where:

You can also specify wildcards (*) to indicate all data objects in a category. For example, you could grant data.read.default.state.* to specify both the car_location and car_fuel_level data objects (and any other data objects) under the state category.

Extend message.create

To extend the message.create, you can append a period ('.') and a string to it. You must grant a separate capability for each message that you want to send.

Note: You can't use a wild card (*) to specify multiple capabilities like data.read or search.read capabilities.

For example, lets say that a target device handles the message types of hello and bye. The capability message.create.hello must be granted to the sending device if you wanted it to send the message type of hello. However, if you wanted the sender to send all message types, you must grant the capability to send each message type individually. In this case, you must grant capabilities for both message.create.hello and message.create.bye. If you had a third message type, you would need to grant that message type as a capability as well.

Assign capabilities

Before you configure an entity to grant another entity a capability (permission) to perform an action on it, you should identify:

You can grant capabilities to entities so that they can perform actions on a target entity. For example, if Entity B is granted the read capability to entity A, Entity B is able to read information from Entity A (target). Capabilities can be granted using the REST API or using the administration console.

For more information about how to grant capabilities, see the information for the respective entity as follows:

Here's an example to help illustrate how to assign a capability that expires at a specific time:

Bob is going to borrow Alice's car. Alice has parked the car in a public parking lot, and Bob is going to pick it up after work. To make it easy for Bob to find her car, Alice gives Bob permission to read the GPS position of her car for the next 23 hours (the current date and time is April 30 at 12:00 PM). In this case, both Bob and Alice are running the same application. Here's how the capability would be configured:

Example

Note: On the administration console, you can see the granted capabilities under the My devices section on the Dashboard in the administration console. For more information, see View devices associated to your account.

Use capability inheritance

Capabilities can be inherited based on where they are granted in to the hierarchy of entities. The hierarchy simply shows how entities to relate to each other. Capabilities that are granted to entities higher in the hierarchy are passed down (inherited) by more devices. For example, if you grant a capability to an organization, all devices of that organization inherit that capability. If you grant a capability to an application, only the devices of that application type inherit the specified capability.

Capabilities can be granted to organizations, applications, devices, and tags. The capabilities that are granted to an entity are useful only for device entities, which are the only entities that can perform actions.

The capabilities that a device has is the superset of capabilities granted to:

For example, the following capabilities are granted to these entities:

The superset of capabilities for the device would be the following if Alison logged in to the device:

However, if Bob logged into the device, his capabilities would be:

Note: It doesn't matter if a capability appears more than once in the hierarchy.

The following illustration shows how capabilities are a superset based on the entity hierarchy based on the above example:

Targets grant capabilities to other entities

Use tags to simplify permission management

Tags are entities that can be granted capabilities, but can also be the target of a capability. When you apply a tag to an entity, the capabilities are transposed to the tagged entity. This concept is described later, but here are some scenarios to help you understand when it's best to use tags:

The user, device, application, and organization entities can have tags applied to them. You can apply one or more tags on an entity. Tags can be either exposing or non-exposing. Here's the difference:

Here are some examples to further illustrate the difference between the two scenarios:

Use of a non-exposing tag is useful when you want only the capabilities that have been granted to a tag to be granted to the tagged entities. For example, a non-exposing Tag XYZ is granted the message.create.ping capability to Application A. After Application B and Device C are tagged with XYZ, both entities have the message.create.ping capability to Application A (target). The following diagram illustrates this concept:

Non-exposing tag

You can use an exposing tag like a non-exposing tag to grant capabilities. This means that the entity that you tagged has the same capabilities that were granted to the tag. An exposing tag can also be a target that grants capabilities to other entities. Entities that are tagged with an exposing tag also grant the same capabilities to entities as the tag does.

For example, Application X is granted capability message.create.update on Tag ABC. If Application Y and Device Z are tagged with ABC, Application X is granted the message.create.update capability on Application Y and Device Z. The following diagram illustrates the concept of how an exposing tag grants the same capabilities to entities that the tag does:

Exposing tag

Use associations to simplify capability management

Another way to simplify the assignment of capabilities to devices is to use associations. Associations grant capabilities to an entity only when both the granting entity (target) and entity being granted the capability are associated to the same user. Associations are useful when you want the BlackBerry IoT Platform to validate the relationship of the entities and when you don't know the UUID of the device to grant a capability to (usually because the device entity hasn't been created). As a user adds more devices, capabilities are automatically granted between devices that they log in to. For example:

All devices that are logged in to by the same user are automatically granted capabilities to read information from each other. Granting a capability as an association by the same user makes this possible.

Association by same user: These associations dynamically assign capabilities between devices that belong to the same user–no matter what organization the user belongs to. This assignment of capabilities helps simplify capability management because you won't have to explicitly assign capabilities to new devices that a user logs in to. For example, Alice owns a car that has an application running, which shares its location. The application entity has associations created that grant data.read and message.create.unlock capability that belong to the same user. The data.read capability allows for other applications belonging to Alice to read the location of the car. The message.create.unlock capability allows an unlock car message to be sent to the car.

Here's an example that illustrates how associations work when a capability has an association configured as by user:

Application X grants read.device and also configures the grant as an association by same user to Application Y. As a result, the devices of Application Y are only able read information of the devices of Application X only if they associated to the same user. If you granted the capability without creating the association by user, it would mean that any device of Application Y could read data on any device of Application X.

Here's a diagram that shows multiple devices how capabilities are granted between devices belonging to the same user.

Association by user

Here's a practical example of how an association by same user would be useful:

Alice just purchased a smart phone that has an application that connects to the BlackBerry IoT Platform. The applications that run on the smart phone and on the car have an association belonging to the same user. After Alice logs in to the application on the smart phone, a new device entity is created on the BlackBerry IoT Platform. That new device is automatically granted capabilities to read the location of the car because the car application was configured to grant the read capability as an association by same user. No additional configuration was required.

In the scenario described above. If the car application didn't grant the capability by association, that new device would need to be explicitly granted to Alice's device on the BlackBerry IoT Platform.

Now you might wonder why you wouldn't simply configure the car application to grant the capability to read data to the smart phone application. They key point to remember is that when you create associations, granting of capabilities based on whether both devices belong to the same user. If you had configured the car application to grant the smart phone application the capability to read the GPS location; then those smart phone applications (no matter who was logged in), would be able to read the location of all car applications. This configuration is probably not what you want or intended.

For more detailed steps about creating and configuring associations, see the following documentation:

Best practices for managing capabilities

Capabilities are required to handle the network of devices and what they can do with one another. Depending on your business rules, you can choose to handle how permissions are configured. However, the following are some general good practices: