{"id":5856,"library":"aws-assume-role-lib","title":"AWS Assume Role Lib","description":"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.","status":"active","version":"2.10.0","language":"en","source_language":"en","source_url":"https://github.com/benkehoe/aws-assume-role-lib","tags":["aws","boto3","iam","assume-role","credentials","security"],"install":[{"cmd":"pip install aws-assume-role-lib","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core library for interacting with AWS services.","package":"boto3","optional":false},{"reason":"Required Python version.","package":"python","optional":false,"version_range":">=3.6,<4.0"}],"imports":[{"note":"The primary function `assume_role` is typically imported directly for brevity.","wrong":"import aws_assume_role_lib; aws_assume_role_lib.assume_role(...)","symbol":"assume_role","correct":"from aws_assume_role_lib import assume_role"},{"note":"Useful for generating session names conforming to Lambda conventions.","symbol":"generate_lambda_session_name","correct":"from aws_assume_role_lib import generate_lambda_session_name"}],"quickstart":{"code":"import os\nimport boto3\nfrom aws_assume_role_lib import assume_role\n\n# Set your target role ARN here, e.g., from an environment variable\n# Ensure the calling principal has 'sts:AssumeRole' permission on this ARN.\nROLE_ARN = os.environ.get('AWS_ASSUME_ROLE_LIB_ROLE_ARN', 'arn:aws:iam::123456789012:role/MyTestRole')\n\nif ROLE_ARN == 'arn:aws:iam::123456789012:role/MyTestRole':\n    print(\"WARNING: Using a placeholder ROLE_ARN. Please set AWS_ASSUME_ROLE_LIB_ROLE_ARN environment variable or replace in code.\")\n\n# Create a parent boto3 session (e.g., from default credentials or a profile)\nparent_session = boto3.Session()\n\ntry:\n    # Assume the role using aws-assume-role-lib\n    assumed_role_session = assume_role(parent_session, ROLE_ARN)\n\n    # Use the assumed role session to create a client or resource\n    sts_client = assumed_role_session.client('sts')\n    caller_identity = sts_client.get_caller_identity()\n    print(f\"Successfully assumed role. Caller ARN: {caller_identity['Arn']}\")\n\n    # Example: Use the assumed role session to list S3 buckets\n    # s3_client = assumed_role_session.client('s3')\n    # buckets = s3_client.list_buckets()\n    # print(f\"Buckets: {[b['Name'] for b in buckets['Buckets']]}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Starting 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.","severity":"breaking","affected_versions":">=2.8.0"},{"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.","message":"In 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.","severity":"breaking","affected_versions":">=2.9.0"},{"fix":"For performance-critical paths where input validity is guaranteed, you can disable this validation by passing `validate=False` to the `assume_role` call.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Direct 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}