Greengrass service role - 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).

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.

Note

Amazon IoT Greengrass V1 also uses this role to perform essential tasks. For more information, see Greengrass service role in the Amazon IoT Greengrass V1 Developer Guide.

To allow Amazon IoT Greengrass to access your resources, the Greengrass service role must be associated with your Amazon Web Services account and specify Amazon IoT Greengrass as a trusted entity. The role must include the AWSGreengrassResourceAccessRolePolicy managed policy or a custom policy that defines equivalent permissions for the Amazon IoT Greengrass features that you use. Amazon maintains this policy, which defines the set of permissions that Amazon IoT Greengrass uses to access your Amazon resources. For more information, see Amazon managed policy: AWSGreengrassResourceAccessRolePolicy.

You can reuse the same Greengrass service role across Amazon Web Services Regions, but you must associate it with your account in every Amazon Web Services Region where you use Amazon IoT Greengrass. If the service role isn't configured in the current Amazon Web Services Region, core devices fail to verify client devices and fail to update connectivity information.

The following sections describe how to create and manage the Greengrass service role with the Amazon Web Services Management Console or Amazon CLI.

Note

In addition to the service role that authorizes service-level access, you assign a token exchange role to Greengrass core devices. The token exchange role is a separate IAM role that controls how Greengrass components and Lambda functions on the core device can access Amazon services. For more information, see Authorize core devices to interact with Amazon services.

Manage the Greengrass service role (console)

The Amazon IoT console makes it easy to manage your Greengrass service role. For example, when you configure client device discovery for a core device, the console checks whether your Amazon Web Services account is attached to a Greengrass service role in the current Amazon Web Services Region. If not, the console can create and configure a service role for you. For more information, see Create the Greengrass service role (console).

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

Note

The user who is signed in to the console must have permissions to view, create, or change the service role.

Find your Greengrass service role (console)

Use the following steps to find the service role that Amazon IoT Greengrass uses in the current Amazon Web Services Region.

  1. Navigate to the Amazon IoT console.

  2. In the navigation pane, choose Settings.

  3. Scroll to the Greengrass service role section to see your service role and its policies.

    If you don't see a service role, the console can create or configure one for you. For more information, see Create the Greengrass service role.

Create the Greengrass service role (console)

The console can create and configure a default Greengrass service role for you. This role has the following properties.

Property Value
Name Greengrass_ServiceRole
Trusted entity Amazon service: greengrass
Policy AWSGreengrassResourceAccessRolePolicy
Note

If you create this role with the Amazon IoT Greengrass V1 device setup script, the role name is GreengrassServiceRole_random-string.

When you configure client device discovery for a core device, the console checks whether a Greengrass service role is associated with your Amazon Web Services account in the current Amazon Web Services Region. If not, the console prompts you to allow Amazon IoT Greengrass to read and write to Amazon services on your behalf.

If you grant permission, the console checks whether a role named Greengrass_ServiceRole exists in your Amazon Web Services account.

  • If the role exists, the console attaches the service role to your Amazon Web Services account in the current Amazon Web Services Region.

  • If the role doesn't exist, the console creates a default Greengrass service role and attaches it to your Amazon Web Services account in the current Amazon Web Services Region.

Note

If you want to create a service role with custom role policies, use the IAM console to create or modify the role. For more information, see Creating a role to delegate permissions to an Amazon service or Modifying a role in the IAM User Guide. Make sure that the role grants permissions that are equivalent to the AWSGreengrassResourceAccessRolePolicy managed policy for the features and resources that you use. 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.

If you create a service role, return to the Amazon IoT console and attach the role to your Amazon Web Services account. You can do this under Greengrass service role on the Settings page.

Change the Greengrass service role (console)

Use the following procedure to choose a different Greengrass service role to attach to your Amazon Web Services account in the Amazon Web Services Region currently selected in the console.

  1. Navigate to the Amazon IoT console.

  2. In the navigation pane, choose Settings.

  3. Under Greengrass service role, choose Change role.

    The Update Greengrass service role dialog box opens and shows the IAM roles in your Amazon Web Services account that define Amazon IoT Greengrass as a trusted entity.

  4. Choose the Greengrass service role to attach.

  5. Choose Attach role.

Detach the Greengrass service role (console)

Use the following procedure to detach the Greengrass service role from your Amazon account in the current Amazon Web Services Region. This revokes permissions for Amazon IoT Greengrass to access Amazon services in the current Amazon Web Services Region.

Important

Detaching the service role might interrupt active operations.

  1. Navigate to the Amazon IoT console.

  2. In the navigation pane, choose Settings.

  3. Under Greengrass service role, choose Detach role.

  4. In the confirmation dialog box, choose Detach.

Note

If you no longer need the role, you can delete it in the IAM console. For more information, see Deleting roles or instance profiles in the IAM User Guide.

Other roles might allow Amazon IoT Greengrass to access your resources. To find all roles that allow Amazon IoT Greengrass to assume permissions on your behalf, in the IAM console, on the Roles page, look for roles that include Amazon service: greengrass in the Trusted entities column.

Manage the Greengrass service role (CLI)

In the following procedures, we assume that the Amazon Command Line Interface is installed and configured to use your Amazon Web Services account. For more information, see Installing, updating, and uninstalling the Amazon CLI and Configuring the Amazon CLI in the Amazon Command Line Interface User Guide.

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

Get the Greengrass service role (CLI)

Use the following procedure to find out if a Greengrass service role is associated with your Amazon Web Services account in an Amazon Web Services Region.

  • Get the service role. Replace region with your Amazon Web Services Region (for example, us-west-2).

    aws greengrassv2 get-service-role-for-account --region region

    If a Greengrass service role is already associated with your account, the request returns the following role metadata.

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

    If the request doesn't return role metadata, then you must create the service role (if it doesn't exist) and associate it with your account in the Amazon Web Services Region.

Create the Greengrass service role (CLI)

Use the following steps to create a role and associate it with your Amazon Web Services account.

To create the service role using IAM
  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
To associate the service role with your Amazon Web Services account
  • Associate the role with your account. Replace role-arn with the service role ARN and region with your Amazon Web Services Region (for example, us-west-2).

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

    If successful, the request returns the following response.

    { "associatedAt": "timestamp" }

Remove the Greengrass service role (CLI)

Use the following steps to disassociate the Greengrass service role from your Amazon Web Services account.

  • Disassociate the service role from your account. Replace region with your Amazon Web Services Region (for example, us-west-2).

    aws greengrassv2 disassociate-service-role-from-account --region region

    If successful, the following response is returned.

    { "disassociatedAt": "timestamp" }
    Note

    You should delete the service role if you're not using it in any Amazon Web Services Region. First use delete-role-policy to detach the AWSGreengrassResourceAccessRolePolicy 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