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

Device authentication and authorization for Amazon IoT Greengrass

Devices in Amazon IoT Greengrass environments use X.509 certificates for authentication and Amazon IoT policies for authorization. Certificates and policies allow devices to securely connect with each other, Amazon IoT Core, and Amazon IoT Greengrass.

X.509 certificates are digital certificates that use the X.509 public key infrastructure standard to associate a public key with the identity contained in a certificate. X.509 certificates are issued by a trusted entity called a certificate authority (CA). The CA maintains one or more special certificates called CA certificates that it uses to issue X.509 certificates. Only the certificate authority has access to CA certificates.

Amazon IoT policies define the set of operations allowed for Amazon IoT devices. Specifically, they allow and deny access to Amazon IoT Core and Amazon IoT Greengrass data plane operations, such as publishing MQTT messages and retrieving device shadows.

All devices require an entry in the Amazon IoT Core registry and an activated X.509 certificate with an attached Amazon IoT policy. Devices fall into two categories:

X.509 certificates

Communication between core devices and client devices and between devices and Amazon IoT Core or Amazon IoT Greengrass must be authenticated. This mutual authentication is based on registered X.509 device certificates and cryptographic keys.

In an Amazon IoT Greengrass environment, devices use certificates with public and private keys for the following Transport Layer Security (TLS) connections:

Amazon IoT Greengrass core devices store certificates in the Greengrass root folder.

Certificate authority (CA) certificates

Greengrass core devices and client devices download a root CA certificate used for authentication with the Amazon IoT Core and Amazon IoT Greengrass services. We recommend that you use an Amazon Trust Services (ATS) root CA certificate, such as Amazon Root CA 1. For more information, see CA certificates for server authentication in the Amazon IoT Core Developer Guide.

Client devices also download a Greengrass core device CA certificate. They use this certificate to validate the MQTT server certificate on the core device during mutual authentication.

Certificate rotation on the local MQTT broker

When you enable client device support, Greengrass core devices generate a local MQTT server certificate that client devices use for mutual authentication. This certificate is signed by the core device CA certificate, which the core device stores in the Amazon IoT Greengrass cloud. Client devices retrieve the core device CA certificate when they discover the core device. They use the core device CA certificate to verify the core device's MQTT server certificate when they connect to the core device. The core device CA certificate expires after 5 years.

The MQTT server certificate expires every 7 days by default, and you can configure this duration to between 2 and 10 days. This limited period is based on security best practices. This rotation helps mitigate the threat of an attacker stealing the MQTT server certificate and private key to impersonate the Greengrass core device.

The Greengrass core device rotates the MQTT server certificate 24 hours before it expires. The Greengrass core device generates a new certificate and restarts the local MQTT broker. When this happens, all client devices connected to the Greengrass core device are disconnected. Client devices can reconnect to the Greengrass core device after a short period of time.

Amazon IoT policies for data plane operations

Use Amazon IoT policies to authorize access to the Amazon IoT Core and Amazon IoT Greengrass data planes. The Amazon IoT Core data plane provides operations for devices, users, and applications. These operations include the ability to connect to Amazon IoT Core and subscribe to topics. The Amazon IoT Greengrass data plane provides operations for Greengrass devices. For more information, see Amazon IoT Greengrass V2 policy actions. These operations include the ability to resolve component dependencies and download public component artifacts.

An Amazon IoT policy is a JSON document that's similar to an IAM policy. It contains one or more policy statements that specify the following properties:

Amazon IoT policies support * as a wildcard character, and treat MQTT wildcard characters (+ and #) as literal strings. For more information about the * wildcard, see Using wildcard in resource ARNs in the Amazon Identity and Access Management User Guide.

For more information, see Amazon IoT policies and Amazon IoT policy actions in the Amazon IoT Core Developer Guide.

Amazon IoT Greengrass V2 policy actions

Amazon IoT Greengrass V2 defines the following policy actions that Greengrass core devices and client devices can use in Amazon IoT policies. To specify a resource for an policy action, you use the Amazon Resource Name (ARN) of the resource.

Update a core device's Amazon IoT policy

You can use the Amazon IoT Greengrass and Amazon IoT consoles or the Amazon IoT API to view and update a core device's Amazon IoT policy.

Minimal Amazon IoT policy for Amazon IoT Greengrass V2 core devices

The following example policy includes the minimum set of actions required to support basic Greengrass functionality for your core device.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Connect"
            ],
            "Resource": "arn:aws-cn:iot:region:account-id:client/core-device-thing-name*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive",
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topic/$aws/things/core-device-thing-name/greengrass/health/json",
                "arn:aws-cn:iot:region:account-id:topic/$aws/things/core-device-thing-name/greengrassv2/health/json",
                "arn:aws-cn:iot:region:account-id:topic/$aws/things/core-device-thing-name/jobs/*",
                "arn:aws-cn:iot:region:account-id:topic/$aws/things/core-device-thing-name/shadow/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topicfilter/$aws/things/core-device-thing-name/jobs/*",
                "arn:aws-cn:iot:region:account-id:topicfilter/$aws/things/core-device-thing-name/shadow/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": "iot:AssumeRoleWithCertificate",
            "Resource": "arn:aws-cn:iot:region:account-id:rolealias/token-exchange-role-alias-name"
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:GetComponentVersionArtifact",
                "greengrass:ResolveComponentCandidates",
                "greengrass:GetDeploymentConfiguration",
                "greengrass:ListThingGroupsForCoreDevice"
            ],
            "Resource": "*"
        }
    ]
}

Minimal Amazon IoT policy to support client devices

The following example policy includes the minimum set of actions required to support interaction with client devices on a core device. To support client devices, a core device must have the permissions in this Amazon IoT policy in addition to the Minimal Amazon IoT policy for basic operation.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topic/$aws/things/core-device-thing-name-gci/shadow/get"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topicfilter/$aws/things/core-device-thing-name-gci/shadow/update/delta",
                "arn:aws-cn:iot:region:account-id:topicfilter/$aws/things/core-device-thing-name-gci/shadow/get/accepted"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topic/$aws/things/core-device-thing-name-gci/shadow/update/delta",
                "arn:aws-cn:iot:region:account-id:topic/$aws/things/core-device-thing-name-gci/shadow/get/accepted"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:PutCertificateAuthorities",
                "greengrass:VerifyClientDeviceIdentity"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:VerifyClientDeviceIoTCertificateAssociation"
            ],
            "Resource": "arn:aws-cn:iot:region:account-id:thing/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:GetConnectivityInfo",
                "greengrass:UpdateConnectivityInfo"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:thing/core-device-thing-name"
            ]
        }
    ]
}

Minimal Amazon IoT policy for client devices

The following example policy includes the minimum set of actions required for a client device to discover core devices where they connect and communicate over MQTT. The client device's Amazon IoT policy must include the greengrass:Discover action to allow the device to discover connectivity information for its associated Greengrass core devices. In the Resource section, specify the Amazon Resource Name (ARN) of the client device, not the ARN of the Greengrass core device.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Connect"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topic/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topicfilter/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topic/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:Discover"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:thing/*"
            ]
        }
    ]
}