Connect client devices to core devices - Amazon IoT Greengrass
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).

Connect client devices to core devices

You can configure cloud discovery to connect client devices to core devices. When you configure cloud discovery, client devices can connect to the Amazon IoT Greengrass cloud service to retrieve information about core devices to which they can connect. Then, the client devices can attempt to connect to each core device until they successfully connect.

To use cloud discovery, you must do the following:

  • Associate client devices to the core devices to which they can connect.

  • Specify the MQTT broker endpoints where client devices can connect to each core device.

  • Deploy components to the core device that enable support for client devices.

    You can also deploy optional components to do the following:

    • Relay messages between client devices, Greengrass components, and the Amazon IoT Core cloud service.

    • Automatically manage core device MQTT broker endpoints for you.

    • Manage local client device shadows and synchronize shadows with the Amazon IoT Core cloud service.

You must also review and update the core device's Amazon IoT policy to verify that it has the permissions required to connect client devices. For more information, see Requirements.

After you configure cloud discovery, you can test communications between a client device and a core device. For more information, see Test client device communications.

Requirements

To connect client devices to a core device, you must have the following:

  • The core device must run Greengrass nucleus v2.2.0 or later.

  • The Greengrass service role associated with Amazon IoT Greengrass for your Amazon Web Services account in the Amazon Region where the core device operates. For more information, see Configure the Greengrass service role.

  • The core device's Amazon IoT policy must allow the following permissions:

    • greengrass:PutCertificateAuthorities

    • greengrass:VerifyClientDeviceIdentity

    • greengrass:VerifyClientDeviceIoTCertificateAssociation

    • greengrass:GetConnectivityInfo

    • greengrass:UpdateConnectivityInfo – (Optional) This permission is required to use the IP detector component, which reports the core device's network connectivity information to the Amazon IoT Greengrass cloud service.

    • iot:GetThingShadow, iot:UpdateThingShadow, and iot:DeleteThingShadow – (Optional) These permissions are required to use the shadow manager component to sync client device shadows with Amazon IoT Core. This feature requires Greengrass nucleus v2.6.0 or later, shadow manager v2.2.0 or later, and MQTT bridge v2.2.0 or later.

    For more information, see Configure the Amazon IoT thing policy.

    Note

    If you used the default Amazon IoT policy when you installed the Amazon IoT Greengrass Core software, the core device has an Amazon IoT policy that allows access to all Amazon IoT Greengrass actions (greengrass:*).

  • Amazon IoT things that you can connect as client devices. For more information, see Create Amazon IoT resources in the Amazon IoT Core Developer Guide.

  • The client device must connect using a client ID. A client ID is a thing name. No other client ID will be accepted.

  • Each client device's Amazon IoT policy must allow the greengrass:Discover permission. For more information, see Minimal Amazon IoT policy for client devices.

Configure the Greengrass service role

The Greengrass service role is an Amazon Identity and Access Management (IAM) service role that authorizes Amazon IoT Greengrass to access resources from Amazon services on your behalf. This role makes it possible for Amazon IoT Greengrass to verify the identity of client devices and manage core device connectivity information.

If you haven't previously set up the Greengrass service role in this Region, you must associate a Greengrass service role with Amazon IoT Greengrass for your Amazon Web Services account in this Region.

When you use the Configure core device discovery page in the Amazon IoT Greengrass console, Amazon IoT Greengrass sets up the Greengrass service role for you. Otherwise, you can manually set it up using the Amazon IoT console or Amazon IoT Greengrass API.

In this section, you check whether the Greengrass service role is set up. If it isn't set up, you create a new Greengrass service role to associate with Amazon IoT Greengrass for your Amazon Web Services account in this Region.

  1. Check if the Greengrass service role is associated with Amazon IoT Greengrass for your Amazon Web Services account in this Region. Do the following:

    1. Navigate to the Amazon IoT console.

    2. In the navigation pane, choose Settings.

    3. In the Greengrass service role section, find Current service role to see whether a Greengrass service role is associated.

      If you have a Greengrass service role associated, you meet this requirement to use the IP detector component. Skip to Configure the Amazon IoT thing policy.

  2. If the Greengrass service role isn't associated with Amazon IoT Greengrass for your Amazon Web Services account in this Region, create a Greengrass service role and associate it. Do the following:

    1. Navigate to the IAM console.

    2. Choose Roles.

    3. Choose Create role.

    4. On the Create role page, do the following:

      1. Under Trusted entity type, choose Amazon Web Services service.

      2. Under Use case, Use cases for other Amazon Web Services services, choose Greengrass, select Greengrass. This option specifies to add Amazon IoT Greengrass as a trusted entity that can assume this role.

      3. Choose Next.

      4. Under Permissions policies, select the AWSGreengrassResourceAccessRolePolicy to attach to the role.

      5. Choose Next.

      6. In Role name, enter a name for the role, such as Greengrass_ServiceRole.

      7. Choose Create role.

    5. Navigate to the Amazon IoT console.

    6. In the navigation pane, choose Settings.

    7. In the Greengrass service role section, choose Attach role.

    8. In the Update Greengrass service role modal, select the IAM role that you created, and then choose Attach role.

  1. Check if the Greengrass service role is associated with Amazon IoT Greengrass for your Amazon Web Services account in this Region.

    aws greengrassv2 get-service-role-for-account

    If the Greengrass service role is associated, the operation returns a response that contains information about the role.

    If you have a Greengrass service role associated, you meet this requirement to use the IP detector component. Skip to Configure the Amazon IoT thing policy.

  2. If the Greengrass service role isn't associated with Amazon IoT Greengrass for your Amazon Web Services account in this Region, create a Greengrass service role and associate it. Do the following:

    1. Create a role with a trust policy that allows Amazon IoT Greengrass to assume the role. This example creates a role named Greengrass_ServiceRole, but you can use a different name. We recommend that you also include the aws:SourceArn and aws:SourceAccount global condition context keys in your trust policy to help prevent the confused deputy security problem. The condition context keys restrict access to allow only those requests that come from the specified account and Greengrass workspace. For more information about the confused deputy problem, see Cross-service confused deputy prevention.

      Linux or Unix
      aws iam create-role --role-name Greengrass_ServiceRole --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "greengrass.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws-cn:greengrass:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ] }'
      Windows Command Prompt (CMD)
      aws iam create-role --role-name Greengrass_ServiceRole --assume-role-policy-document "{\\"Version\\":\\"2012-10-17\\",\\"Statement\\":[{\\"Effect\\":\\"Allow\\",\\"Principal\\":{\\"Service\\":\\"greengrass.amazonaws.com\\"},\\"Action\\":\\"sts:AssumeRole\\",\\"Condition\\":{\\"ArnLike\\":{\\"aws:SourceArn\\":\\"arn:aws-cn:greengrass:region:account-id:*\\"},\\"StringEquals\\":{\\"aws:SourceAccount\\":\\"account-id\\"}}}]}"
      PowerShell
      aws iam create-role --role-name Greengrass_ServiceRole --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "greengrass.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws-cn:greengrass:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ] }'
    2. Copy the role ARN from the role metadata in the output. You use the ARN to associate the role with your account.

    3. Attach the AWSGreengrassResourceAccessRolePolicy policy to the role.

      aws iam attach-role-policy --role-name Greengrass_ServiceRole --policy-arn arn:aws-cn:iam::aws:policy/service-role/AWSGreengrassResourceAccessRolePolicy
    4. Associate the Greengrass service role with Amazon IoT Greengrass for your Amazon Web Services account. Replace role-arn with the ARN of the service role.

      aws greengrassv2 associate-service-role-to-account --role-arn role-arn

      The operation returns the following response if it succeeds.

      { "associatedAt": "timestamp" }

Configure the Amazon IoT thing policy

Core devices use X.509 device certificates to authorize connections to Amazon. You attach Amazon IoT policies to device certificates to define the permissions for a core device. For more information, see Amazon IoT policies for data plane operations and Minimal Amazon IoT policy to support client devices.

To connect client devices to a core device, the core device's Amazon IoT policy must allow the following permissions:

  • greengrass:PutCertificateAuthorities

  • greengrass:VerifyClientDeviceIdentity

  • greengrass:VerifyClientDeviceIoTCertificateAssociation

  • greengrass:GetConnectivityInfo

  • greengrass:UpdateConnectivityInfo – (Optional) This permission is required to use the IP detector component, which reports the core device's network connectivity information to the Amazon IoT Greengrass cloud service.

  • iot:GetThingShadow, iot:UpdateThingShadow, and iot:DeleteThingShadow – (Optional) These permissions are required to use the shadow manager component to sync client device shadows with Amazon IoT Core. This feature requires Greengrass nucleus v2.6.0 or later, shadow manager v2.2.0 or later, and MQTT bridge v2.2.0 or later.

In this section, you review the Amazon IoT policies for your core device and add any required permissions that are missing. If you used the Amazon IoT Greengrass Core software installer to provision resources, your core device has an Amazon IoT policy that allows access to all Amazon IoT Greengrass actions (greengrass:*). In this case, you must update the Amazon IoT policy only if you plan to deploy the shadow manager component to sync device shadows with Amazon IoT Core. Otherwise, you can skip this section.

  1. In the Amazon IoT Greengrass console navigation menu, choose Core devices.

  2. On the Core devices page, choose the core device to update.

  3. On the core device details page, choose the link to the core device's Thing. This link opens the thing details page in the Amazon IoT console.

  4. On the thing details page, choose Certificates.

  5. In the Certificates tab, choose the thing's active certificate.

  6. On the certificate details page, choose Policies.

  7. In the Policies tab, choose the Amazon IoT policy to review and update. You can add the required permissions to any policy that is attached to the core device's active certificate.

    Note

    If you used the Amazon IoT Greengrass Core software installer to provision resources, you have two Amazon IoT policies. We recommend that you choose the policy named GreengrassV2IoTThingPolicy, if it exists. Core devices that you create with the quick installer use this policy name by default. If you add permissions to this policy, you are also granting these permissions to other core devices that use this policy.

  8. In the policy overview, choose Edit active version.

  9. Review the policy for the required permissions, and add any required permissions that are missing.

    • greengrass:PutCertificateAuthorities

    • greengrass:VerifyClientDeviceIdentity

    • greengrass:VerifyClientDeviceIoTCertificateAssociation

    • greengrass:GetConnectivityInfo

    • greengrass:UpdateConnectivityInfo – (Optional) This permission is required to use the IP detector component, which reports the core device's network connectivity information to the Amazon IoT Greengrass cloud service.

    • iot:GetThingShadow, iot:UpdateThingShadow, and iot:DeleteThingShadow – (Optional) These permissions are required to use the shadow manager component to sync client device shadows with Amazon IoT Core. This feature requires Greengrass nucleus v2.6.0 or later, shadow manager v2.2.0 or later, and MQTT bridge v2.2.0 or later.

  10. (Optional) To allow the core device to sync shadows with Amazon IoT Core, add the following statement to the policy. If you plan to interact with client device shadows, but not sync them with Amazon IoT Core, skip this step. Replace region and account-id with the Region that you use and your Amazon Web Services account number.

    • This example statement allows access to all things' device shadows. To follow best security practices, you can restrict access to only the core device and the client devices that you connect to the core device. For more information, see Minimal Amazon IoT policy to support client devices.

    { "Effect": "Allow", "Action": [ "iot:GetThingShadow", "iot:UpdateThingShadow", "iot:DeleteThingShadow" ], "Resource": [ "arn:aws-cn:iot:region:account-id:thing/*" ] }

    After you add this statement, the policy document might look similar to the following example.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect", "iot:Publish", "iot:Subscribe", "iot:Receive", "greengrass:*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "iot:GetThingShadow", "iot:UpdateThingShadow", "iot:DeleteThingShadow" ], "Resource": [ "arn:aws-cn:iot:region:account-id:thing/*" ] } ] }
  11. To set a new policy version as the active version, under Policy version status, select Set the edited version as the active version for this policy.

  12. Choose Save as new version.

  1. List the principals for the core device's Amazon IoT thing. Thing principals can be X.509 device certificates or other identifies. Run the following command, and replace MyGreengrassCore with the name of the core device.

    aws iot list-thing-principals --thing-name MyGreengrassCore

    The operation returns a response that lists the core device's thing principals.

    { "principals": [ "arn:aws:iot:us-west-2:123456789012:cert/certificateId" ] }
  2. Identify the core device's active certificate. Run the following command, and replace certificateId with the ID of each certificate from the previous step until you find the active certificate. The certificate ID is the hexadecimal string at the end of the certificate ARN. The --query argument specifies to output only the certificate's status.

    aws iot describe-certificate --certificate-id certificateId --query 'certificateDescription.status'

    The operation returns the certificate status as a string. For example, if the certificate is active, this operation outputs "ACTIVE".

  3. List the Amazon IoT policies that are attached to the certificate. Run the following command, and replace the certificate ARN with the ARN of the certificate.

    aws iot list-principal-policies --principal arn:aws:iot:us-west-2:123456789012:cert/certificateId

    The operation returns a response that lists the Amazon IoT policies that are attached to the certificate.

    { "policies": [ { "policyName": "GreengrassTESCertificatePolicyMyGreengrassCoreTokenExchangeRoleAlias", "policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassTESCertificatePolicyMyGreengrassCoreTokenExchangeRoleAlias" }, { "policyName": "GreengrassV2IoTThingPolicy", "policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassV2IoTThingPolicy" } ] }
  4. Choose the policy to view and update.

    Note

    If you used the Amazon IoT Greengrass Core software installer to provision resources, you have two Amazon IoT policies. We recommend that you choose the policy named GreengrassV2IoTThingPolicy, if it exists. Core devices that you create with the quick installer use this policy name by default. If you add permissions to this policy, you are also granting these permissions to other core devices that use this policy.

  5. Get the policy's document. Run the following command, and replace GreengrassV2IoTThingPolicy with the name of the policy.

    aws iot get-policy --policy-name GreengrassV2IoTThingPolicy

    The operation returns a response that contains the policy's document and other information about the policy. The policy document is a JSON object serialized as a string.

    { "policyName": "GreengrassV2IoTThingPolicy", "policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassV2IoTThingPolicy", "policyDocument": "{\ \\"Version\\": \\"2012-10-17\\",\ \\"Statement\\": [\ {\ \\"Effect\\": \\"Allow\\",\ \\"Action\\": [\ \\"iot:Connect\\",\ \\"iot:Publish\\",\ \\"iot:Subscribe\\",\ \\"iot:Receive\\",\ \\"greengrass:*\\"\ ],\ \\"Resource\\": \\"*\\"\ }\ ]\ }", "defaultVersionId": "1", "creationDate": "2021-02-05T16:03:14.098000-08:00", "lastModifiedDate": "2021-02-05T16:03:14.098000-08:00", "generationId": "f19144b798534f52c619d44f771a354f1b957dfa2b850625d9f1d0fde530e75f" }
  6. Use an online converter or other tool to convert the policy document string to a JSON object, and then save it to a file named iot-policy.json.

    For example, if you have the jq tool installed, you can run the following command to get the policy document, convert it to a JSON object, and save the policy document as a JSON object.

    aws iot get-policy --policy-name GreengrassV2IoTThingPolicy --query 'policyDocument' | jq fromjson >> iot-policy.json
  7. Review the policy for the required permissions, and add any required permissions that are missing.

    For example, on a Linux-based system, you can run the following command to use GNU nano to open the file.

    nano iot-policy.json
    • greengrass:PutCertificateAuthorities

    • greengrass:VerifyClientDeviceIdentity

    • greengrass:VerifyClientDeviceIoTCertificateAssociation

    • greengrass:GetConnectivityInfo

    • greengrass:UpdateConnectivityInfo – (Optional) This permission is required to use the IP detector component, which reports the core device's network connectivity information to the Amazon IoT Greengrass cloud service.

    • iot:GetThingShadow, iot:UpdateThingShadow, and iot:DeleteThingShadow – (Optional) These permissions are required to use the shadow manager component to sync client device shadows with Amazon IoT Core. This feature requires Greengrass nucleus v2.6.0 or later, shadow manager v2.2.0 or later, and MQTT bridge v2.2.0 or later.

  8. Save the changes as a new version of the policy. Run the following command, and replace GreengrassV2IoTThingPolicy with the name of the policy.

    aws iot create-policy-version --policy-name GreengrassV2IoTThingPolicy --policy-document file://iot-policy.json --set-as-default

    The operation returns a response similar to the following example if it succeeds.

    { "policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassV2IoTThingPolicy", "policyDocument": "{\ \\"Version\\": \\"2012-10-17\\",\ \\"Statement\\": [\ {\ \\"Effect\\": \\"Allow\\",\ \\"Action\\": [\ \\t\\t\\"iot:Connect\\",\ \\t\\t\\"iot:Publish\\",\ \\t\\t\\"iot:Subscribe\\",\ \\t\\t\\"iot:Receive\\",\ \\t\\t\\"greengrass:*\\"\ ],\ \\"Resource\\": \\"*\\"\ }\ ]\ }", "policyVersionId": "2", "isDefaultVersion": true }

Greengrass components for client device support

Important

The core device must run Greengrass nucleus v2.2.0 or later to support client devices.

To enable client devices to connect and communicate with a core device, you deploy the following Greengrass components to the core device:

  • Client device auth (aws.greengrass.clientdevices.Auth)

    Deploy the client device auth component to authenticate client devices and authorize client device actions. This component allows your Amazon IoT things to connect to a core device.

    This component requires some configuration to use it. You must specify groups of client devices and the operations that each group is authorized to perform, such as to connect and communicate over MQTT. For more information, see client device auth component configuration.

  • MQTT 3.1.1 broker (Moquette) (aws.greengrass.clientdevices.mqtt.Moquette)

    Deploy the Moquette MQTT broker component to run a lightweight MQTT broker. The Moquette MQTT broker is compliant with MQTT 3.1.1 and includes local support for QoS 0, QoS 1, QoS 2, retained messages, last will messages, and persistent subscriptions.

    You aren't required to configure this component to use it. However, you can configure the port where this component operates the MQTT broker. By default, it uses port 8883.

  • MQTT 5 broker (EMQX) (aws.greengrass.clientdevices.mqtt.EMQX)

    Note

    To use the EMQX MQTT 5 broker, you must use Greengrass nucleus v2.6.0 or later and client device auth v2.2.0 or later.

    Deploy the EMQX MQTT broker component to use MQTT 5.0 features in communication between client devices and the core device. The EMQX MQTT broker is compliant with MQTT 5.0 and includes support for session and message expiration intervals, user properties, shared subscriptions, topic aliases, and more.

    You aren't required to configure this component to use it. However, you can configure the port where this component operates the MQTT broker. By default, it uses port 8883.

  • MQTT bridge (aws.greengrass.clientdevices.mqtt.Bridge)

    (Optional) Deploy the MQTT bridge component to relay messages between client devices (local MQTT), local publish/subscribe, and Amazon IoT Core MQTT. Configure this component to sync client devices with Amazon IoT Core and interact with client devices from Greengrass components.

    This component requires configuration to use. You must specify the topic mappings where this component relays messages. For more information, see MQTT bridge component configuration.

  • IP detector (aws.greengrass.clientdevices.IPDetector)

    (Optional) Deploy the IP detector component to automatically report the core device's MQTT broker endpoints to the Amazon IoT Greengrass cloud service. You cannot use this component if you have a complex network setup, such as one where a router forwards the MQTT broker port to the core device.

    You aren't required to configure this component to use it.

  • Shadow manager (aws.greengrass.ShadowManager)

    Note

    To manage client device shadows, you must use Greengrass nucleus v2.6.0 or later, shadow manager v2.2.0 or later, and MQTT bridge v2.2.0 or later.

    (Optional) Deploy the shadow manager component to manage client device shadows on the core device. Greengrass components can get, update, and delete client device shadows to interact with client devices. You can also configure the shadow manager component to synchronize client device shadows with the Amazon IoT Core cloud service.

    To use this component with client device shadows, you must configure the MQTT bridge component to relay messages between client devices and shadow manager, which uses local publish/subscribe. Otherwise, this component doesn't require configuration to use, but it does require configuration to sync device shadows.

Note

We recommend that you deploy only one MQTT broker component. The MQTT bridge and IP detector components work with only one MQTT broker component at a time. If you deploy multiple MQTT broker components, you must configure them to use different ports.

Configure cloud discovery (console)

You can use the Amazon IoT Greengrass console to associate client devices, manage core device endpoints, and deploy components to enable client device support. For more information, see Step 2: Enable client device support.

Configure cloud discovery (Amazon CLI)

You can use the Amazon Command Line Interface (Amazon CLI) to associate client devices, manage core device endpoints, and deploy components to enable client device support. For more information, see the following: