boto3-assume 0.1.1

Easily create boto3/aioboto3 assume role sessions with automatic credential refreshing.

boto3-assume

boto3-assume has one simple goal. Easily create boto3/aioboto3 assume role sessions with automatic credential refreshing.

Installation

Install with pip:

$ pip install boto3-assume

It doesn't come with boto3 or aioboto3 by default, but if you want to install them with the package it can be done as extras.

$ pip install boto3-assume[aioboto,boto3]

Tutorial

There are only 2 functions assume_role_session and assume_role_aio_session

For boto3:

import boto3
from boto3_assume import assume_role_session

assume_session = assume_role_session(
    source_session=boto3.Session(), # You must pass in a boto3 session that automatically refreshes!
    RoleArn="arn:aws:iam::123412341234:role/my_role",
    RoleSessionName="my-role-session"
)

# Create clients, and their credentials will auto-refresh when expired!
sts_client = assume_session.client("sts", region_name="us-east-1")
print(sts_client.get_caller_identity())
# {
#     "UserId": "EXAMPLEID", 
#     "Account": "123412341234", 
#     "Arn": "arn:aws:sts::123412341234:role/my_role", 
#     "ResponseMetadata": {
#         "RequestId": "asdfqwfqwfasdfasdfasfsdf", 
#         "HTTPStatusCode": 200, 
#         "HTTPHeaders": {
#             "server": "amazon.com", 
#             "date": "Tue, 27 Jun 2023 00:00:00 GMT"
#         }, 
#         "RetryAttempts": 0
#     }
# }

For aioboto3:

import asyncio

import aioboto3
from boto3_assume import assume_role_aio_session

# since this uses "Deferred" credentials you don't need to call this within a coroutine or context manager
assume_session = assume_role_session(
    source_session=aioboto3.Session(), # You must pass in an aioboto3 session that automatically refreshes!
    RoleArn="arn:aws:iam::123412341234:role/my_role",
    RoleSessionName="my-role-session"
)

async def main():
    # Create clients, and their credentials will auto-refresh when expired!
    async with assume_session.client("sts", region_name="us-east-1") as sts_client:
        print(await sts_client.get_caller_identity())
        # {
        #     "UserId": "EXAMPLEID", 
        #     "Account": "123412341234", 
        #     "Arn": "arn:aws:sts::123412341234:role/my_role", 
        #     "ResponseMetadata": {
        #         "RequestId": "asdfqwfqwfasdfasdfasfsdf", 
        #         "HTTPStatusCode": 200, 
        #         "HTTPHeaders": {
        #             "server": "amazon.com", 
        #             "date": "Tue, 27 Jun 2023 00:00:00 GMT"
        #         }, 
        #         "RetryAttempts": 0
        #     }
        # }

asyncio.run(main())

Under the hood a boto3/aioboto3 sts client will be created and assume_role called to get/refresh credentials.

If you want you can also specify extra kwargs for the sts client, and for the assume_role call.

NOTE: The "sts" service is already specified for the client. RoleArn and RoleSessionName are used in the assume role call.

import boto3
from boto3_assume import assume_role_session
from botocore.config import Config

assume_session = assume_role_session(
    source_session=boto3.Session(), # You must pass in a boto3 session that automatically refreshes!
    RoleArn="arn:aws:iam::123412341234:role/my_role",
    RoleSessionName="my-role-session",
    sts_client_kwargs={
        "region_name": "us-east-1",
        "config": Config(
            retries={
                "total_max_attempts": 10,
                "mode": "adaptive"
            }
        )
    },
    assume_role_kwargs={
        "DurationSeconds": 900
    }
)

Development

Install the package in editable mode with dev dependencies.

(venv) $ pip install -e .[dev,all]

nox is used to manage various dev functions. Start with

(venv) $ nox --help

pyenv is used to manage python versions. To run the nox tests for applicable python version you will first need to install them. In the root project dir run:

(venv) $ pyenv install

Changelog

Changelog for boto3-assume. All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.1.1] - 2023-06-28

Fixed

- Formatting for Changelog, README

[0.1.0] - 2023-06-28

Initial Release.