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 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:

The Amazon IoT Greengrass core device stores certificates in two locations:

For more information, see Amazon IoT Greengrass core security principals.

Certificate authority (CA) certificates

Core devices and client devices download a root CA certificate used for authentication with 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 the Greengrass group CA certificate. This is used to validate the MQTT server certificate on the Greengrass core during mutual authentication. For more information, see Device connection workflow. The default expiration of the MQTT server certificate is seven days.

Certificate rotation on the local MQTT server

Client devices use the local MQTT server certificate for mutual authentication with the Greengrass core device. By default, this certificate expires in seven days. This limited period is based on security best practices. The MQTT server certificate is signed by the group CA certificate, which is stored in the cloud.

For certificate rotation to occur, your Greengrass core device must be online and able to access the Amazon IoT Greengrass service directly on a regular basis. When the certificate expires, the core device attempts to connect to the Amazon IoT Greengrass service to obtain a new certificate. If the connection is successful, the core device downloads a new MQTT server certificate and restarts the local MQTT service. At this point, all client devices that are connected to the core are disconnected. If the core device is offline at the time of expiry, it does not receive the replacement certificate. Any new attempts to connect to the core device are rejected. Existing connections are not affected. Client devices cannot connect to the core device until the connection to the Amazon IoT Greengrass service is restored and a new MQTT server certificate can be downloaded.

You can set the expiration to any value between 7 and 30 days, depending on your needs. More frequent rotation requires more frequent cloud connection. Less frequent rotation can pose security concerns. If you want to set the certificate expiration to a value higher than 30 days, contact Amazon Web Services Support.

In the Amazon IoT console, you can manage the certificate on the group's Settings page. In the Amazon IoT Greengrass API, you can use the UpdateGroupCertificateConfiguration action.

When the MQTT server certificate expires, any attempt to validate the certificate fails. Client devices must be able to detect the failure and terminate the connection.

Amazon IoT policies for data plane operations

Use Amazon IoT policies to authorize access to the Amazon IoT Core and Amazon IoT Greengrass data plane. The Amazon IoT Core data plane consists of operations for devices, users, and applications, such as connecting to Amazon IoT Core and subscribing to topics. The Amazon IoT Greengrass data plane consists of operations for Greengrass devices, such as retrieving deployments and updating connectivity information.

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 policy actions

Minimal Amazon IoT policy for the Amazon IoT Greengrass core device

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-name-*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish",
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topic/$aws/things/core-name-*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:topicfilter/$aws/things/core-name-*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:GetThingShadow",
                "iot:UpdateThingShadow",
                "iot:DeleteThingShadow"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:thing/core-name-*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:AssumeRoleForGroup",
                "greengrass:CreateCertificate"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:GetDeployment"
            ],
            "Resource": [
                "arn:aws-cn:greengrass:region:account-id:/greengrass/groups/group-id/deployments/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:GetDeploymentArtifacts"
            ],
            "Resource": [
                "arn:aws-cn:greengrass:region:account-id:/greengrass/groups/group-id/deployments/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:UpdateCoreDeploymentStatus"
            ],
            "Resource": [
                "arn:aws-cn:greengrass:region:account-id:/greengrass/groups/group-id/deployments/*/cores/arn%3Aaws%3Aiot%3Aregion%3Aaccount-id%3Athing%2Fcore-name"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "greengrass:GetConnectivityInfo",
                "greengrass:UpdateConnectivityInfo"
            ],
            "Resource": [
                "arn:aws-cn:iot:region:account-id:thing/core-name-*"
            ]
        }
    ]
}

{
    "Effect": "Allow",
    "Action": [
        "greengrass:Discover"
    ],
    "Resource": [
        "arn:aws-cn:iot:region:account-id:thing/device-name"
    ]
}

In the Amazon IoT console, you can view and edit the policy that's attached to your core's certificate.