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).

Retained message policy examples

Using retained messages requires specific policies. Retained messages are MQTT messages published with the RETAIN flag set and stored by Amazon IoT Core. This section presents examples of policies that allow common uses of retained messages.

Policy to connect and publish retained messages

For a device to publish retained messages, the device must be able to connect, publish (any MQTT message), and publish MQTT retained messages. The following policy grants these permissions for the topic: device/sample/configuration to client device1. For another example that grants permission to connect, see Connect and publish policy examples.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"iot:Connect"
			],
			"Resource": [
				"arn:aws:iot:us-east-1:123456789012:client/device1"
			]
		},
		{
			"Effect": "Allow",
			"Action": [
				"iot:Publish",
				"iot:RetainPublish"
			],
			"Resource": [
				"arn:aws:iot:us-east-1:123456789012:topic/device/sample/configuration"
			]
		}
	]
}

Policy to connect and publish retained Will messages

Clients can configure a message that Amazon IoT Core will publish when the client disconnects unexpectedly. MQTT calls such a message a Will message. A client must have an additional condition added to its connect permission to include them.

The following policy document grants all clients permission to connect and publish a Will message, identified by its topic, will, that Amazon IoT Core will also retain.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"iot:Connect"
			],
			"Resource": [
				"arn:aws:iot:us-east-1:123456789012:client/device1"
			],
			"Condition": {
				"ForAllValues:StringEquals": {
					"iot:ConnectAttributes": [
						"LastWill"
					]
				}
			}
		},
		{
			"Effect": "Allow",
			"Action": [
				"iot:Publish",
				"iot:RetainPublish"
			],
			"Resource": [
				"arn:aws:iot:us-east-1:123456789012:topic/will"
			]
		}
	]
}

Policy to list and get retained messages

Services and applications can access retained messages without the need to support an MQTT client by calling ListRetainedMessages and GetRetainedMessage. The services and applications that call these actions must be authorized by using a policy such as the following example.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"iot:ListRetainedMessages"
			],
			"Resource": [
				"arn:aws:iot:us-east-1:123456789012:client/device1"
			],
		},
		{
			"Effect": "Allow",
			"Action": [
				"iot:GetRetainedMessage"
			],
			"Resource": [
				"arn:aws:iot:us-east-1:123456789012:topic/foo"
			]
		}
	]
}