awsiot-credentialhelper

AWS IoT Core Credential Provider Session Helper

This package provides an easy way to create a refreshable Boto3 Session using the AWS IoT Core credential provider.

Package documentation

Features

• Automatic refresh of Boto3 credentials through requests to the AWS IoT Core credential provider. No need to manage or maintain refresh times.
• Uses the underlying AWS CRT Python bindings for querying the credential provider instead of the Python standard library. This provides support for both certificate and private keys as files or as environment variables.
• Extensible to using other TLS methods such as PKCS#11 hardware security modules (see Advanced section).
• Only requires four function calls to create a session helper, Boto3 session, Boto3 client, and then client API calls.

Requirements

• Python 3.8 - 3.11. Support not include for 3.7 as that version will be end of life in June, 2023. If 3.7 support is important, please open an issue to discuss.

Installation

You can install AWS IoT Core Credential Provider Session Helper via pip from PyPI:

python3 -m pip install awsiot-credentialhelper

Usage

Prior to use, ensure all cloud-side resources for IAM and AWS IoT Core have been properly created and configured. Then, with the AWS IoT registered X.509 certificate and corresponding private key (e.g., iot_thing.pem and iot_thing.pem.key), you can create and use the helper as follows:

from awsiot_credentialhelper.boto3_session import Boto3SessionProvider

# Create boto3 session object
boto3_session = Boto3SessionProvider(
    endpoint="your_endpoint.credentials.iot.us-west-2.amazonaws.com",
    role_alias="your_aws_iot_role_alias_name",
    certificate="iot_thing.pem",
    private_key="iot_thing.pem.key",
    thing_name="iot_thing",
).get_session()

# Use in regular Boto3 chained operations, such as returning caller identity
print(boto3_session.client("sts").get_caller_identity())
{'UserId': 'AROA...F3D:4686c...0a0d', 'Account': '1234567890', 'Arn': 'arn:aws:sts::1234567890:assumed-role/iam_role_name/4686c...0a0d', 'ResponseMetadata': {'RequestId': 'cc04...10bc', 'HTTPStatusCode': 200, 'HTTPHeaders': {'x-amzn-requestid': 'cc04...10bc', 'content-type': 'text/xml', 'content-length': '554', 'date': 'Tue, 21 Feb 2023 21:18:23 GMT'}, 'RetryAttempts': 0}}

# Or by creating a service client and making API calls
iot = boto3_session.client("iot")
result = iot.list_things()

Please see the package documentation for more details and advanced use.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the Apache 2.0 license. Details on third party packages used by this package can be found here.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project template was generated from a fork of @cjolowicz's Hypermodern Python Cookiecutter template.