Greengrass group role - Amazon IoT Greengrass
Manage the group role (console)Manage the group role (CLI)See also
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).

Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Greengrass group role

The Greengrass group role is an IAM role that authorizes code running on a Greengrass core to access your Amazon resources. You create the role and manage permissions in Amazon Identity and Access Management (IAM) and attach the role to your Greengrass group. A Greengrass group has one group role. To add or change permissions, you can attach a different role or change the IAM policies that are attached to the role.

The role must define Amazon IoT Greengrass as a trusted entity. Depending on your business case, the group role might contain IAM policies that define:

The following sections describe how to attach or detach a Greengrass group role in the Amazon Web Services Management Console or Amazon CLI.

Note

In addition to the group role that authorizes access from the Greengrass core, you can assign a Greengrass service role that allows Amazon IoT Greengrass to access Amazon resources on your behalf.

Managing the Greengrass group role (console)

You can use the Amazon IoT console for the following role management tasks:

Note

The user who is signed in to the console must have permissions to manage the role.

 

Find your Greengrass group role (console)

Follow these steps to find the role that is attached to a Greengrass group.

  1. In the Amazon IoT console navigation pane, under Manage, expand Greengrass devices, and then choose Groups (V1).

  2. Choose the target group.

  3. On the group configuration page, choose View settings.

If a role is attached to the group, it appears under Group role.

 

Add or change the Greengrass group role (console)

Follow these steps to choose an IAM role from your Amazon Web Services account to add to a Greengrass group.

A group role has the following requirements:

  • Amazon IoT Greengrass defined as a trusted entity.

  • The permission policies attached to the role must grant the permissions to your Amazon resources that are required by the Lambda functions and connectors in the group, and by Greengrass system components.

Note

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.

Use the IAM console to create and configure the role and its permissions. For steps that create an example role that allows access to an Amazon DynamoDB table, see Configure the group role. For general steps, see Creating a role for an Amazon service (console) in the IAM User Guide.

 

After the role is configured, use the Amazon IoT console to add the role to the group.

Note

This procedure is required only to choose a role for the group. It's not required after changing the permissions of the currently selected group role.

  1. In the Amazon IoT console navigation pane, under Manage, expand Greengrass devices, and then choose Groups (V1).

  2. Choose the target group.

  3. On the group configuration page, choose View settings.

  4. Under Group role, choose to add or change the role:

    • To add the role, choose Associate role and then select your role from your list of roles. These are the roles in your Amazon Web Services account that define Amazon IoT Greengrass as a trusted entity.

    • To choose a different role, choose Edit role and then select your role from your list of roles.

  5. Choose Save.

 

Remove the Greengrass group role (console)

Follow these steps to detach the role from a Greengrass group.

  1. In the Amazon IoT console navigation pane, under Manage, expand Greengrass devices, and then choose Groups (V1).

  2. Choose the target group.

  3. On the group configuration page, choose View settings.

  4. Under Group role, choose Disassociate role.

  5. In the confirmation dialog box, choose Disassociate role. This step removes the role from the group but doesn't delete the role. If you want to delete the role, use the IAM console.

Managing the Greengrass group role (CLI)

You can use the Amazon CLI for the following role management tasks:

 

Get the Greengrass group role (CLI)

Follow these steps to find out if a Greengrass group has an associated role.

  1. Get the ID of the target group from the list of your groups.

    aws greengrass list-groups

    The following is an example list-groups response. Each group in the response includes an Id property that contains the group ID.

    {
    "Groups": [
        {
            "LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE/versions/4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
            "Name": "MyFirstGroup",
            "LastUpdatedTimestamp": "2019-11-11T05:47:31.435Z",
            "LatestVersion": "4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
            "CreationTimestamp": "2019-11-11T05:47:31.435Z",
            "Id": "00dedaaa-ac16-484d-ad77-c3eedEXAMPLE",
            "Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE"
        },
        {
            "LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE/versions/8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
            "Name": "GreenhouseSensors",
            "LastUpdatedTimestamp": "2020-01-07T19:58:36.774Z",
            "LatestVersion": "8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
            "CreationTimestamp": "2020-01-07T19:58:36.774Z",
            "Id": "036ceaf9-9319-4716-ba2a-237f9EXAMPLE",
            "Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE"
        },
        ...
    ]
}

    For more information, including examples that use the query option to filter results, see Getting the group ID.

  2. Copy the Id of the target group from the output.

  3. Get the group role. Replace group-id with the ID of the target group.

    aws greengrass get-associated-role --group-id group-id

    If a role is associated with your Greengrass group, the following role metadata is returned.

    {
  "AssociatedAt": "timestamp",
  "RoleArn": "arn:aws-cn:iam::account-id:role/path/role-name"
}

    If your group doesn't have an associated role, the following error is returned.

    An error occurred (404) when calling the GetAssociatedRole operation: You need to attach an IAM role to this deployment group.

 

Create the Greengrass group role (CLI)

Follow these steps to create a role and associate it with a Greengrass group.

To create the group role using IAM

  1. Create the role with a trust policy that allows Amazon IoT Greengrass to assume the role. This example creates a role named MyGreengrassGroupRole, 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, macOS, or Unix
    aws iam create-role --role-name MyGreengrassGroupRole --assume-role-policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "greengrass.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "account-id"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws-cn:greengrass:region:account-id:/greengrass/groups/group-id"
        }
      }
    }
  ]
}'
    Windows command prompt
    aws iam create-role --role-name MyGreengrassGroupRole --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:/greengrass/groups/group-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 group.

  3. Attach managed or inline policies to the role to support your business case. For example, if a user-defined Lambda function reads from Amazon S3, you might attach the AmazonS3ReadOnlyAccess managed policy to the role.

    aws iam attach-role-policy --role-name MyGreengrassGroupRole --policy-arn arn:aws-cn:iam::aws:policy/AmazonS3ReadOnlyAccess

    If successful, no response is returned.

 

To associate the role with your Greengrass group

  1. Get the ID of the target group from the list of your groups.

    aws greengrass list-groups

    The following is an example list-groups response. Each group in the response includes an Id property that contains the group ID.

    {
    "Groups": [
        {
            "LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE/versions/4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
            "Name": "MyFirstGroup",
            "LastUpdatedTimestamp": "2019-11-11T05:47:31.435Z",
            "LatestVersion": "4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
            "CreationTimestamp": "2019-11-11T05:47:31.435Z",
            "Id": "00dedaaa-ac16-484d-ad77-c3eedEXAMPLE",
            "Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE"
        },
        {
            "LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE/versions/8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
            "Name": "GreenhouseSensors",
            "LastUpdatedTimestamp": "2020-01-07T19:58:36.774Z",
            "LatestVersion": "8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
            "CreationTimestamp": "2020-01-07T19:58:36.774Z",
            "Id": "036ceaf9-9319-4716-ba2a-237f9EXAMPLE",
            "Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE"
        },
        ...
    ]
}

    For more information, including examples that use the query option to filter results, see Getting the group ID.

  2. Copy the Id of the target group from the output.

  3. Associate the role with your group. Replace group-id with the ID of the target group and role-arn with the ARN of the group role.

    aws greengrass associate-role-to-group --group-id group-id --role-arn role-arn

    If successful, the following response is returned.

    {
  "AssociatedAt": "timestamp"
}

 

Remove the Greengrass group role (CLI)

Follow these steps to disassociate the group role from your Greengrass group.

  1. Get the ID of the target group from the list of your groups.

    aws greengrass list-groups

    The following is an example list-groups response. Each group in the response includes an Id property that contains the group ID.

    {
    "Groups": [
        {
            "LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE/versions/4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
            "Name": "MyFirstGroup",
            "LastUpdatedTimestamp": "2019-11-11T05:47:31.435Z",
            "LatestVersion": "4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
            "CreationTimestamp": "2019-11-11T05:47:31.435Z",
            "Id": "00dedaaa-ac16-484d-ad77-c3eedEXAMPLE",
            "Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE"
        },
        {
            "LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE/versions/8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
            "Name": "GreenhouseSensors",
            "LastUpdatedTimestamp": "2020-01-07T19:58:36.774Z",
            "LatestVersion": "8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
            "CreationTimestamp": "2020-01-07T19:58:36.774Z",
            "Id": "036ceaf9-9319-4716-ba2a-237f9EXAMPLE",
            "Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE"
        },
        ...
    ]
}

    For more information, including examples that use the query option to filter results, see Getting the group ID.

  2. Copy the Id of the target group from the output.

  3. Disassociate the role from your group. Replace group-id with the ID of the target group.

    aws greengrass disassociate-role-from-group --group-id group-id

    If successful, the following response is returned.

    {
  "DisassociatedAt": "timestamp"
}
    Note

    You can delete the group role if you're not using it. First use delete-role-policy to detach each managed policy from the role, and then use delete-role to delete the role. For more information, see Deleting roles or instance profiles in the IAM User Guide.

See also