Thing policy variables - Amazon IoT Core
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Thing policy variables

Thing policy variables allow you to write Amazon IoT Core policies that grant or deny permissions based on thing properties like thing names, thing types, and thing attribute values. You can use thing policy variables to apply the same policy to control many Amazon IoT Core devices. For more information about device provisioning, see Device Provisioning. The thing name is obtained from the client ID in the MQTT Connect message sent when a thing connects to Amazon IoT Core.

Keep the following in mind when using thing policy variables in Amazon IoT Core policies.

  • Use the AttachThingPrincipal API to attach certificates or principals (authenticated Amazon Cognito identities) to a thing.

  • When you're replacing thing names with thing policy variables, the value of clientId in the MQTT connect message or the TLS connection must exactly match the thing name.

The following thing policy variables are available:

  • iot:Connection.Thing.ThingName

    This resolves to the name of the thing in the Amazon IoT Core registry for which the policy is being evaluated. Amazon IoT Core uses the certificate the device presents when it authenticates to determine which thing to use to verify the connection. This policy variable is only available when a device connects over MQTT or MQTT over the WebSocket protocol.

  • iot:Connection.Thing.ThingTypeName

    This resolves to the thing type associated with the thing for which the policy is being evaluated. The client ID of the MQTT/WebSocket connection must be the same as the thing name. This policy variable is available only when connecting over MQTT or MQTT over the WebSocket protocol.

  • iot:Connection.Thing.Attributes[attributeName]

    This resolves to the value of the specified attribute associated with the thing for which the policy is being evaluated. A thing can have up to 50 attributes. Each attribute is available as a policy variable: iot:Connection.Thing.Attributes[attributeName] where attributeName is the name of the attribute. The client ID of the MQTT/WebSocket connection must be the same as the thing name. This policy variable is only available when connecting over MQTT or MQTT over the WebSocket protocol.

  • iot:Connection.Thing.IsAttached

    iot:Connection.Thing.IsAttached: ["true"] enforces that only the devices that are both registered in Amazon IoT and attached to principal can access the permissions inside the policy. You can use this variable to prevent a device from connecting to Amazon IoT Core if it presents a certificate that is not attached to an IoT thing in the Amazon IoT Core registry.This variable has values true or false indicating that the connecting thing is attached to the certificate or Amazon Cognito identity in the registry using AttachThingPrincipal API. Thing name is taken as client Id.

If your client ID matches your thing name, or if you attach your certificate to a thing exclusively, using policy variables in the policy definition can simplify policy management. Instead of creating individual policies for each IoT thing, you can define a single policy using the thing policy variables. This policy can be applied to all devices dynamically. The following is an example policy to show how it works. For more information, see Associating an Amazon IoT thing to an MQTT client connection.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Condition": {
				"StringLike": {
					"iot:ClientId": "*${iot:Connection.Thing.Attributes[envType]}"
				}
			},
			"Effect": "Allow",
			"Action": "iot:Connect",
			"Resource": "arn:aws:iot:us-east-1:123456789012:client/*"
		}
	]
}

This policy example allows things to connect to Amazon IoT Core if their client ID ends with the value of their envType attribute. Only things with a matching client ID pattern will be allowed to connect.