Registry / aws / aws-assume-role-lib

aws-assume-role-lib

library2.10.0pypypi✓ verified 21d ago

aws-assume-role-lib simplifies assumed role session chaining with automatic credential refreshing for boto3. As of version 2.10.0, released May 14, 2022, it provides an abstraction layer over `sts.AssumeRole` to handle credential expiration and session name generation, common in serverless environments like AWS Lambda. The library maintains a steady release cadence, with updates addressing new boto3 features and CLI support.

aws

pip install aws-assume-role-lib

github ↗package ↗

INSTALL

IMPORT

SIG · AWS-ASSUME-ROLE-LI

aws-assume-role-lib

awspythonv2.10.0

Install

3.7s avg

Import

708ms

Disk

50MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.10.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.742s · 51.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.7s · import 0.674s · 52MB

50MB installed

● package 50MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

assume_role

✓ from aws_assume_role_lib import assume_role

✗ import aws_assume_role_lib; aws_assume_role_lib.assume_role(...)

The primary function `assume_role` is typically imported directly for brevity.

generate_lambda_session_name

✓ from aws_assume_role_lib import generate_lambda_session_name

Useful for generating session names conforming to Lambda conventions.

This quickstart demonstrates how to create a parent `boto3` session and then use `aws_assume_role_lib.assume_role` to get a new session with assumed role credentials. The assumed session automatically handles credential refreshing. Ensure the `ROLE_ARN` environment variable is set or replace the placeholder.

import os import boto3 from aws_assume_role_lib import assume_role # Set your target role ARN here, e.g., from an environment variable # Ensure the calling principal has 'sts:AssumeRole' permission on this ARN. ROLE_ARN = os.environ.get('AWS_ASSUME_ROLE_LIB_ROLE_ARN', 'arn:aws:iam::123456789012:role/MyTestRole') if ROLE_ARN == 'arn:aws:iam::123456789012:role/MyTestRole': print("WARNING: Using a placeholder ROLE_ARN. Please set AWS_ASSUME_ROLE_LIB_ROLE_ARN environment variable or replace in code.") # Create a parent boto3 session (e.g., from default credentials or a profile) parent_session = boto3.Session() try: # Assume the role using aws-assume-role-lib assumed_role_session = assume_role(parent_session, ROLE_ARN) # Use the assumed role session to create a client or resource sts_client = assumed_role_session.client('sts') caller_identity = sts_client.get_caller_identity() print(f"Successfully assumed role. Caller ARN: {caller_identity['Arn']}") # Example: Use the assumed role session to list S3 buckets # s3_client = assumed_role_session.client('s3') # buckets = s3_client.list_buckets() # print(f"Buckets: {[b['Name'] for b in buckets['Buckets']]}") except Exception as e: print(f"An error occurred: {e}")

Debug

Known issues

breakingStarting with v2.8, the library introduced 'compatibility version 2', indicating potential breaking changes. Specifically, the behavior of `region_name=None` for child sessions was changed to link to the parent session's region rather than copying it, which can affect implicit region resolution.

fix

Review how `region_name` is used in `assume_role` calls. Explicitly set `region_name=True` to fix the child session's region to the parent's current value, or pass a specific string for a fixed region.

affects: >=2.8.0

breakingIn v2.9, the logic for generating `RoleSessionName` when `SourceIdentity` is provided was updated. If `RoleSessionName` is not explicitly set but `SourceIdentity` is, `SourceIdentity` will be used for `RoleSessionName`. This differs from pre-v2.8 behavior where a `botocore`-generated value was always used.

fix

If you relied on the `botocore`-generated `RoleSessionName` when `SourceIdentity` was present, set `RoleSessionName` to `aws_assume_role_lib.AUTOMATIC_ROLE_SESSION_NAME` to restore the pre-2.8 behavior.

affects: >=2.9.0

gotcha`assume_role()` performs parameter validation by default, which adds a small time penalty. This validation helps catch issues before the child session is first used, as `boto3` defers credential retrieval.

fix

For performance-critical paths where input validity is guaranteed, you can disable this validation by passing `validate=False` to the `assume_role` call.

affects: All versions

gotchaThe `assume_role()` function in `aws-assume-role-lib` offers enhanced parameter types compared to the raw `boto3 sts.AssumeRole` API. Specifically, `Policy` can be a Python dictionary (instead of a JSON string), `PolicyArns` can be a list of strings (instead of a list of dicts), and `DurationSeconds` can be a `datetime.timedelta` object (instead of an integer).

fix

Be aware of these type differences when migrating code or referencing `boto3`'s `AssumeRole` documentation. Leverage the convenient Python types for easier policy and duration management.

affects: All versions

gotchaDirect usage of `boto3.client('sts').assume_role()` requires manual handling of credential expiration and refreshing, and explicit provision of a `RoleSessionName`. `aws-assume-role-lib` abstracts these complexities.

fix

Utilize `aws-assume-role-lib.assume_role()` for automatic credential refreshing and session name generation, which is particularly beneficial in long-running processes or serverless functions.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'aws_assume_role_lib'

The 'aws-assume-role-lib' package is not installed or not found in the Python environment.

fix

Install the package using pip: 'pip install aws-assume-role-lib'.

ImportError: cannot import name 'assume_role' from 'aws_assume_role_lib'

The function 'assume_role' is not found in the 'aws_assume_role_lib' module, possibly due to an incorrect import statement.

fix

Ensure the import statement is correct: 'from aws_assume_role_lib import assume_role'.

botocore.exceptions.ClientError: An error occurred (AccessDenied) when calling the AssumeRole operation: User is not authorized to perform: sts:AssumeRole on resource

The IAM user or role lacks the necessary permissions to perform the 'sts:AssumeRole' action.

fix

Update the IAM policy to grant 'sts:AssumeRole' permission for the specified role.

botocore.exceptions.ClientError: An error occurred (ExpiredToken) when calling the AssumeRole operation: The security token included in the request is expired

The temporary security credentials have expired.

fix

Refresh the credentials by re-assuming the role or obtaining new temporary credentials.

ValueError: RoleArn must be provided

The 'RoleArn' parameter is missing when calling the 'assume_role' function.

fix

Provide the 'RoleArn' parameter when calling 'assume_role', e.g., 'assume_role(session, RoleArn="arn:aws:iam::123456789012:role/MyRole")'.

Upgrade

Version history

2.10.0latest on PyPI · released May 14, 2022

Audit

Dependencies

boto3requiredCore library for interacting with AWS services.

pythonrequiredRequired Python version.

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/benkehoe/aws-assume-role-lib ↗

packagehttps://pypi.org/project/aws-assume-role-lib/ ↗