The Internet of Things on AWS – Official Blog

Improving the management and security of your AWS IoT resources with tagging

Solution providers operating environments such as smart building, utilities, manufacturing systems, and connected products offer business-to-business services often based on IoT platforms deployed in multitenant deployments. Securely managing those resources by use case, types, locations and by tenants can sometime be hard.

Creating hierarchical grouping of things is a common pattern, but it does not address multitenancy well. For instance, the same tenant might rent offices in several cities and share some buildings with other tenants, and this cannot be captured by creating hierarchical groups. On the other hand, the same resources might be used over time by different tenants (such as a connected vehicle, a rented office space, or connected device).

In this post, we walk through how to use AWS tags on multitenant IoT deployments to improve management and security of AWS IoT resources in such environments. We first discuss why tagging resources is important, and then we dig into AWS IoT tagging capabilities. We then go through the steps of setting up tags and using tags for a fictional multitenant smart building environment.


Why is tagging resources important?

Tags are labels in the form of a key-value pair that can be attached to your AWS resources. They provide additional information and context about that specific resource. Tags can identify who owns the resource, the environment where it is used, and any other technical or business attributes based on your requirements.

An effective tagging policy allows you to track all of your AWS resources from different services. Manage them according to your requirements, by building your own set of resources grouped by tags.

Tagging can serve various purposes. The most common use of tags is to control cost allocation. AWS Cost Explorer uses tags allocated to resources to break down AWS cost by tags, and you can create detailed billing reports accordingly. Tags also allow grouping cost from various services (AWS IoT Core, Amazon EC2 instances, Amazon S3 buckets, AWS Lambda functions, and others) consumed in a particular context (for example, consumed for one project or by one tenant of a shared IoT service).

Different tags can flag all resources of a given tenant, business unit, cost center, customer, project, application, or any dimension, allowing granular and consolidated approach to cost allocation.

Another direct benefit of tags is to allow filtering resources on the AWS Management Console based on tags or portions of tags. This allows you to see all resources related to a project, organization, or any grouping relevant to the operation of your environment. It creates a custom console for you. This is based on the resource groups that can be set either through the console or through the resource group API.  AWS IoT Analytics, AWS IoT Core, AWS IoT Device Defender, and AWS IoT Device Management support resource groups.

Tags can also serve your security policies by allowing access control based on tags. IAM policies can be configured to define resource policies based on tags. Using tags with IAM policies allows controlling access to a group of resources based on their tag values.

Tags can be used to identify which resources are involved in some automated activities, for example, development resources that should be stopped after business hours. Tags can also identify device groups that can be involved in specific AWS IoT Device Defender audits.

To serve those different purposes, you can create your own tagging strategy based on AWS tagging strategies best practices.


IoT-specific tagging capabilities

First, given the potentially huge number of connected things, IoT things cannot be directly tagged. Instead, groups of things can be tagged. So, apply your tagging strategy to groups of things.

Things can be grouped in different ways. The AWS IoT Core device registry allows creation of hierarchical thing groups—a thing can belong to several groups. In a later example, things are grouped by location (each floor of the building forming a group of devices). You can apply a tag to such a group.

You can also define dynamic groups, where group membership is defined by query rules on device connectivity status, shadow values, or registry parameters, making the group dynamic.  You might, for instance, create a group for sensors that display a temperature higher than 25°C, and another one for all device currently connected and ready to receive downstream data and commands. Applying tags to such dynamic groups allows you to quickly identify the devices related to those dynamic groups and take appropriate actions.

Billing groups are groups of things created for billing purposes that collect billable information for the things.

You can tag each billing group that you create to identify which tenant, business unit within a tenant, product, or project things are being used for. This is part of the AWS cost allocation report with your usage and costs aggregated by your tags.

A thing can only belong to a single billing group, and billing groups cannot be organized in hierarchies. For more details on billing groups capabilities, see billing groups capabilities.

You can also tag other AWS IoT Core resources:

  • Thing type—several thing types can be tagged to match either a specific group of similar things types.
  • Topic rules can be tagged to match a specific application using this rule.
  • Jobs, scheduled audits, and security profiles can also be tagged to facilitate automation.

Applying tags to a multitenant AWS IoT deployment

In this example, you learn how to apply tags to thing types, hierarchical thing groups, and billing groups by going through an example of a multitenant smart building IoT setup.

A fictitious company, ExampleCorp, offers office spaces for rent to various businesses and provides energy-efficient and wellness office services. Those services rely on smart devices such as smart lights, presence sensors, temperature sensors, and air quality sensors. To manage its building parks, ExampleCorp is using AWS IoT services. ExampleCorp must manage things according to their types and creates several thing types.

Defining and tagging thing types

First, define thing types to clearly identify the various types of things that ExampleCorp is using. In the AWS IoT Core console, choose Manage,  Types.

When creating thing types on the console, you can directly apply tags. Alternately, tags can also be set by going through the tagging API. Allocating a tag to this thing type allows quick listing and applying of actions to a set of similar things, both from CLI or API.

When you choose LightBulbs thing type, you get details on this thing type and on the tag applied to this type.

When thing types have been properly tagged, you can easily list all the thing types tagged with a specific tag. The following is an example of retrieving all thing types produced by the manufacturer AnyCompany1 , who is providing both TemperatureSensor and LightBulb-versionA thing types to ExampleCorp

[]  aws resourcegroupstaggingapi get-resources --tag-filters Key="Manufacturer",Values="AnyCompany1" | awk -F\/  '/ResourceARN/ {print $2}' | awk -F \" '{print $1}')

TemperatureSensor LightBulb-versionA

From this point, all things of this thing type can be listed and used for either accounting, or as entry to an AWS IoT job command.

Grouping things logically and tagging groups

After having properly created and tagged thing types, ExampleCorp has onboarded a few devices in the AWS IoT Core console.

In addition, to facilitate service delivery and management, ExampleCorp decides to organize things grouping by use case and by floor.

To create groups, in the AWS IoT Core console, choose Manage, groups.

The following diagram shows a hierarchical group for light bulbs, split in sub groups representing the various locations when smart lightbulbs are deployed. Select the “Groups” Tab under the LightBulbs group to list all subgroups:

AWS IoT Things Groups


You can navigate this hierarchy by clicking on group names (Building1FirstFloor, Building1SecondFloor Building2) and you can add subgroups with the “add a group” command.

Thing groups have a hierarchical structure that fits well with organizing things according to their location (building, floor) and use case. However, ExampleCorp wants to quickly identify the set of devices that their customers use.

While it is possible to list all things within a group, allocating tags to various thing groups allows quick listing and applying of actions to a group of things, both from CLI or API. In this example, a tag representing the customer who uses the things is allocated to the thing groups.

In the following screenshot, AnyCompany2  company is renting the first and third floors of Building 2, and an appropriate tag (customerName = AnyCompany2) has been set up for those thing groups. The following IOT Console screenshot shows the tags applied to the things group representing the first floor of Building 2. Select the “Tag” Tab under the LightBulbs group to display the tags associated to this group:

AWS IoT Groups Resource Tags
When ExampleCorp wants to list which things are being used by a particular customer, they can run a CLI command. The following code example lists all things from the thing group being used by a particular customer. In this example, list all things from thing group with the tag CustomerName = “AnyCompany2”.

#Get the list of all resource groups tagged for the customer
# First, retrieve the thing group tagged for this customer
[]  aws resourcegroupstaggingapi get-resources --tag-filters Key="customerName",Values="AnyCompany2" | awk -F\/  '/ResourceARN/ {print $2}' | awk -F \" '{print $1}')

#Use those group names to retrieve the list of things within these groups

[]  aws iot  list-things-in-thing-group   --thing-group-name ThirdFloor
    "things": [
aws iot  list-things-in-thing-group   --thing-group-name firstFloor
    "things": [

Creating relevant billing groups

Billing groups are the basic unit for charging in AWS IoT.  You can assign billing groups to things, individually, whether they are part of a group or not.

In our example, Example Corp decides to create one billing group for each building floor for all things within this floor.

The following commands create a billing group for the things in the First Floor of the Building 2, and automatically adds a tag to this group to spot its location.

aws iot create-billing-group  --billing-group-name Building2FirstFloorLightBulbs --tags Key="Location",Value="Building2-FirstFloor"
    "billingGroupArn": "arn:aws:iot:us-east-1:453102091241:billinggroup/Building2FirstFloorLightBulbs",
    "billingGroupId": "af885c88-15b2-4f3d-8809-287e07c56338",
    "billingGroupName": "Building2FirstFloorLightBulbs

It is a best practice, when possible, to allocate things to billing group at thing creation time. When this is not possible, you must add things individually to the billing group.


In our example, ExampleCorp allocates things to the billing groups created for each area. The following CLI commands shows how to add things individually to an existing billing group.

#add one thing to billing group
[]   aws iot add-thing-to-billing-group --billing-group-name Building2FirstFloorLightBulbs --thing-name lightBulbs53

When building areas are rented to a customer, billing groups can be tagged with the customer’s name.

For example, if AnyCompany2 rents the First floor of building 2, this billing group may be tagged with a specific Tag CustomerName=AnyCompany2.

Now, the previously created billing group is now tagged to the appropriate customer name (AnyCompany2).

[]   aws resourcegroupstaggingapi tag-resources --resource-arn-list arn:aws:iot:us-east-1:453102091241:billinggroup/Building2FirstFloorLightBulbs --tags  "customerName"="AnyCompany2"
    "FailedResourcesMap": {}

The previous command successfully added the tag in the billing group. To display billing groups in the AWS IoT Core console, choose Manage, Billing Groups, and select the billing group to display:


AWS IoT Billing Groups

This same tag can be used for non-IoT resources to be part of cost allocation tags. When activated, cost allocation tags can be used as a dimension of grouping and filtering in Cost Explorer, as well as for refining AWS budget criteria.

Using tags with an IAM policy example

Another common use of tags is to have a fine-grained configurable set of IAM policies.

The following policy can be attached to any user related to a specific tenant (for instance, AnyCompany2 in this example) to allow them to send updates to device shadows. This is achieved by checking that both principal (the user) and resources (The Billing Group) have the same customerName tag (AnyCompany2).

    "Version": "2012-10-17",
    "Statement": [
            "Effect": "Allow",
            "Action": "iot:UpdateBillingGroup",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/customerName": "${aws:PrincipalTag/customerName}"

To see a list of AWS IoT condition keys, see Condition Keys for AWS IoT in the IAM User Guide. To learn with which actions and resources you can use a condition key, see Actions Defined by AWS IoT.

The tagging is essential to tenant security. Policies can prevent unauthorized users from acting on tags, and to restrict which tag keys and values can be set to a resource or passed to an AWS command. For more information, see this tutorial on using tags for attribute-based Access control.


In this post, we walked you through a multitenant use case to depict how tagging can enhance the following:

  • Manageability of resources according to tenants
  • Billing, by providing accurate and by tenant billing statements
  • Security policies to allow granular control by tenants, based on tag checking

You should now be ready to define your own tagging strategy to improve the management and security of your AWS IoT resources.