Interact with Amazon services - 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).

Interact with Amazon services

Greengrass core devices use X.509 certificates to connect to Amazon IoT Core using TLS mutual authentication protocols. These certificates let devices interact with Amazon IoT without Amazon credentials, which typically comprise an access key ID and a secret access key. Other Amazon services require Amazon credentials instead of X.509 certificates to call API operations at service endpoints. Amazon IoT Core has a credentials provider that enables devices to use their X.509 certificate to authenticate Amazon requests. The Amazon IoT credentials provider authenticates devices using an X.509 certificate and issues Amazon credentials in the form a temporary, limited-privilege security token. Devices can use this token to sign and authenticate any Amazon request. This eliminates the need to store Amazon credentials on Greengrass core devices. For more information, see Authorizing direct calls to Amazon services in the Amazon IoT Core Developer Guide.

To fetch credentials from Amazon IoT, Greengrass, core devices use an Amazon IoT role alias that points to an IAM role. This IAM role is called the token exchange role. You create the role alias and token exchange role when you install the Amazon IoT Greengrass Core software. To specify the role alias that a core device uses, configure the iotRoleAlias parameter of the Greengrass nucleus.

The Amazon IoT credentials provider assumes the token exchange role on your behalf to provide Amazon credentials to core devices. You can attach appropriate IAM policies to this role to allow your core devices access to your Amazon resources, such as components artifacts in S3 buckets. For more information about how to configure the token exchange role, see Authorize core devices to interact with Amazon services.

Greengrass core devices store Amazon credentials in memory, and the credentials expire after an hour by default. If the Amazon IoT Greengrass Core software restarts, it must fetch credentials again. You can use the UpdateRoleAlias operation to configure the duration that credentials are valid.

Amazon IoT Greengrass provides a public component, the token exchange service component, that you can define as a dependency in your custom component to interact with Amazon services. The token exchange service provides your component with an environment variable, AWS_CONTAINER_CREDENTIALS_FULL_URI, that defines the URI to a local server that provides Amazon credentials. When you create an Amazon SDK client, the client checks for this environment variable and connects to the local server to retrieve Amazon credentials and uses them to sign API requests. This lets you use Amazon SDKs and other tools to call Amazon services in your components. For more information, see Token exchange service.


Support to acquire Amazon credentials in this way was added to the Amazon SDKs on July 13th, 2016. Your component must use an Amazon SDK version that was created on or after that date. For more information, see Using a supported Amazon SDK in the Amazon Elastic Container Service Developer Guide.

To acquire Amazon credentials in your custom component, define aws.greengrass.TokenExchangeService as a dependency in the component recipe. The following example recipe defines a component that installs boto3 and runs a Python script that uses Amazon credentials from the token exchange service to list Amazon S3 buckets.


To run this example component, your device must have the s3:ListAllMyBuckets permission. For more information, see Authorize core devices to interact with Amazon services.

{ "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.ListS3Buckets", "ComponentVersion": "1.0.0", "ComponentDescription": "A component that uses the token exchange service to list S3 buckets.", "ComponentPublisher": "Amazon", "ComponentDependencies": { "aws.greengrass.TokenExchangeService": { "VersionRequirement": "^2.0.0", "DependencyType": "HARD" } }, "Manifests": [ { "Platform": { "os": "linux" }, "Lifecycle": { "install": "pip3 install --user boto3", "run": "python3 -u {artifacts:path}/" } }, { "Platform": { "os": "windows" }, "Lifecycle": { "install": "pip3 install --user boto3", "run": "py -3 -u {artifacts:path}/" } } ] }
--- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.ListS3Buckets ComponentVersion: '1.0.0' ComponentDescription: A component that uses the token exchange service to list S3 buckets. ComponentPublisher: Amazon ComponentDependencies: aws.greengrass.TokenExchangeService: VersionRequirement: '^2.0.0' DependencyType: HARD Manifests: - Platform: os: linux Lifecycle: install: pip3 install --user boto3 run: |- python3 -u {artifacts:path}/ - Platform: os: windows Lifecycle: install: pip3 install --user boto3 run: |- py -3 -u {artifacts:path}/

This example component runs the following Python script, that lists Amazon S3 buckets.

import boto3 import os try: print("Creating boto3 S3 client...") s3 = boto3.client('s3') print("Successfully created boto3 S3 client") except Exception as e: print("Failed to create boto3 s3 client. Error: " + str(e)) exit(1) try: print("Listing S3 buckets...") response = s3.list_buckets() for bucket in response['Buckets']: print(f'\t{bucket["Name"]}') print("Successfully listed S3 buckets") except Exception as e: print("Failed to list S3 buckets. Error: " + str(e)) exit(1)