Connect client devices to core devices

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.

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

   2. Under Use case, Use cases for other Amazon Web 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.

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.

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"
   }

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

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

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.

On the thing details page, choose Certificates.

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

On the certificate details page, choose Policies.

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.

In the policy overview, choose Edit active version.

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

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

{
  "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/*"
      ]
    }
  ]
}

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.

Choose Save as new version.

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"
    ]
}

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

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"
        }
    ]
}

Choose the policy to view and update.

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"
}

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

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

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
}