Authorize core devices to interact with Amazon services - Amazon IoT Greengrass
Service role permissions for core devicesAllow access to S3 buckets for component artifacts
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).

Authorize core devices to interact with Amazon services

Amazon IoT Greengrass core devices use the Amazon IoT Core credentials provider to authorize calls to Amazon services. The Amazon IoT Core credentials provider enables devices to use their X.509 certificates as the unique device identity to authenticate Amazon requests. This eliminates the need to store an Amazon access key ID and secret access key on your Amazon IoT Greengrass core devices. For more information, see Authorizing direct calls to Amazon services in the Amazon IoT Core Developer Guide.

When you run the Amazon IoT Greengrass Core software, you can choose to provision the Amazon resources that the core device requires. This includes the Amazon Identity and Access Management (IAM) role that your core device assumes through the Amazon IoT Core credentials provider. Use the --provision true argument to configure a role and policies that allow the core device to get temporary Amazon credentials. This argument also configures an Amazon IoT role alias that points to this IAM role. You can specify the name of the IAM role and Amazon IoT role alias to use. If you specify --provision true without these other name parameters, the Greengrass core device creates and uses the following default resources:

  • IAM role: GreengrassV2TokenExchangeRole

    This role has a policy named GreengrassV2TokenExchangeRoleAccess and a trust relationship that allows credentials.iot.amazonaws.com to assume the role. The policy includes the minimum permissions for the core device.

    Important

    This policy doesn't include access to files in S3 buckets. You must add permissions to the role to allow core devices to retrieve component artifacts from S3 buckets. For more information, see Allow access to S3 buckets for component artifacts.

  • Amazon IoT role alias: GreengrassV2TokenExchangeRoleAlias

    This role alias refers to the IAM role.

For more information, see Step 3: Install the Amazon IoT Greengrass Core software.

You can also set the role alias for an existing core device. To do so, configure the iotRoleAlias configuration parameter of the Greengrass nucleus component.

You can acquire temporary Amazon credentials for this IAM role to perform Amazon operations in your custom components. For more information, see Interact with Amazon services.

Service role permissions for core devices

The role allows the following service to assume the role:

  • credentials.iot.amazonaws.com

If you use the Amazon IoT Greengrass Core software to create this role, it uses the following permissions policy to allow core devices to connect and send logs to Amazon. The policy's name defaults to the name of the IAM role ending with Access. For example, if you use the default IAM role name, then this policy's name is GreengrassV2TokenExchangeRoleAccess.

Greengrass nucleus v2.5.0 and later
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogStreams",
        "s3:GetBucketLocation"
      ],
      "Resource": "*"
    }
  ]
}
v2.4.x
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:DescribeCertificate",
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogStreams",
        "s3:GetBucketLocation"
      ],
      "Resource": "*"
    }
  ]
}
Earlier than v2.4.0
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:DescribeCertificate",
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogStreams",
        "iot:Connect",
        "iot:Publish",
        "iot:Subscribe",
        "iot:Receive",
        "s3:GetBucketLocation"
      ],
      "Resource": "*"
    }
  ]
}

Allow access to S3 buckets for component artifacts

The default core device role doesn't allow core devices to access S3 buckets. To deploy components that have artifacts in S3 buckets, you must add the s3:GetObject permission to allow core devices to download component artifacts. You can add a new policy to the core device role to grant this permission.

To add a policy that allows access to component artifacts in Amazon S3

  1. Create a file called component-artifact-policy.json and copy the following JSON into the file. This policy allows access to all files in an S3 bucket. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket to allow the core device to access.

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET/*"
    }
  ]
}

  2. Run the following command to create the policy from the policy document in component-artifact-policy.json.

    Linux or Unix
    aws iam create-policy \
  --policy-name MyGreengrassV2ComponentArtifactPolicy \
  --policy-document file://component-artifact-policy.json
    Windows Command Prompt (CMD)
    aws iam create-policy ^
  --policy-name MyGreengrassV2ComponentArtifactPolicy ^
  --policy-document file://component-artifact-policy.json
    PowerShell
    aws iam create-policy `
  --policy-name MyGreengrassV2ComponentArtifactPolicy `
  --policy-document file://component-artifact-policy.json

    Copy the policy Amazon Resource Name (ARN) from the policy metadata in the output. You use this ARN to attach this policy to the core device role in the next step.

  3. Run the following command to attach the policy to the core device role. Replace GreengrassV2TokenExchangeRole with the name of the role that you specified when you ran the Amazon IoT Greengrass Core software. Then, replace the policy ARN with the ARN from the previous step.

    Linux or Unix
    aws iam attach-role-policy \
  --role-name GreengrassV2TokenExchangeRole \
  --policy-arn arn:aws-cn:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
    Windows Command Prompt (CMD)
    aws iam attach-role-policy ^
  --role-name GreengrassV2TokenExchangeRole ^
  --policy-arn arn:aws-cn:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
    PowerShell
    aws iam attach-role-policy `
  --role-name GreengrassV2TokenExchangeRole `
  --policy-arn arn:aws-cn:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy

    If the command has no output, it succeeded, and your core device can access artifacts that you upload to this S3 bucket.