boto3-refresh-session


Nameboto3-refresh-session JSON
Version 1.3.18 PyPI version JSON
download
home_pagehttps://github.com/michaelthomasletts/boto3-refresh-session
SummaryA simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.
upload_time2025-07-12 11:45:56
maintainerMichael Letts
docs_urlNone
authorMike Letts
requires_python>=3.10
licenseMIT
keywords boto3 botocore aws sts ecs credentials token refresh
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <div align="center">
  <img src="https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/brs.png" />
</div>

</br>

<div align="center"><em>
  A simple Python package for refreshing the temporary security credentials in a <code>boto3.session.Session</code> object automatically.
</em></div>

</br>

<div align="center">

  <a href="https://pypi.org/project/boto3-refresh-session/">
    <img src="https://img.shields.io/pypi/v/boto3-refresh-session?color=%23FF0000FF&logo=python&label=Latest%20Version" alt="PyPI - Version"/>
  </a>

  <a href="https://pypi.org/project/boto3-refresh-session/">
    <img src="https://img.shields.io/pypi/pyversions/boto3-refresh-session?style=pypi&color=%23FF0000FF&logo=python&label=Compatible%20Python%20Versions" alt="Python Version"/>
  </a>

  <a href="https://github.com/michaelthomasletts/boto3-refresh-session/actions/workflows/push.yml">
    <img src="https://img.shields.io/github/actions/workflow/status/michaelthomasletts/boto3-refresh-session/push.yml?logo=github&color=%23FF0000FF&label=Build" alt="Workflow"/>
  </a>

  <a href="https://github.com/michaelthomasletts/boto3-refresh-session/commits/main">
    <img src="https://img.shields.io/github/last-commit/michaelthomasletts/boto3-refresh-session?logo=github&color=%23FF0000FF&label=Last%20Commit" alt="GitHub last commit"/>
  </a>

  <a href="https://github.com/michaelthomasletts/boto3-refresh-session/stargazers">
    <img src="https://img.shields.io/github/stars/michaelthomasletts/boto3-refresh-session?style=flat&logo=github&labelColor=555&color=FF0000&label=Stars" alt="Stars"/>
  </a>

  <a href="https://pypistats.org/packages/boto3-refresh-session">
    <img src="https://img.shields.io/badge/downloads-72.1K-red?logo=python&color=%23FF0000&label=Downloads%20%28with%20mirrors%29" alt="Downloads with mirrors"/>
  </a>

  <a href="https://pypistats.org/packages/boto3-refresh-session">
    <img src="https://img.shields.io/badge/downloads-18.1K-red?logo=python&color=%23FF0000&label=Downloads%20%28without%20mirrors%29" alt="Downloads without mirrors"/>
  </a>  

  <a href="https://michaelthomasletts.github.io/boto3-refresh-session/index.html">
    <img src="https://img.shields.io/badge/Official%20Documentation-📘-FF0000?style=flat&labelColor=555&logo=readthedocs" alt="Documentation Badge"/>
  </a>

  <a href="https://github.com/michaelthomasletts/boto3-refresh-session">
    <img src="https://img.shields.io/badge/Source%20Code-💻-FF0000?style=flat&labelColor=555&logo=github" alt="Source Code Badge"/>
  </a>

  <a href="https://michaelthomasletts.github.io/boto3-refresh-session/qanda.html">
    <img src="https://img.shields.io/badge/Q%26A-❔-FF0000?style=flat&labelColor=555&logo=vercel&label=Q%26A" alt="Q&A Badge"/>
  </a>

  <a href="https://medium.com/@lettsmt/you-shouldnt-have-to-think-about-refreshing-aws-credentials-214f7cbbd83b">
    <img src="https://img.shields.io/badge/Medium%20Article-📘-FF0000?style=flat&labelColor=555&logo=readthedocs" alt="Medium Article"/>
  </a>

<a href="https://github.com/sponsors/michaelthomasletts">
  <img src="https://img.shields.io/badge/Sponsor%20this%20Project-💙-FF0000?style=flat&labelColor=555&logo=githubsponsors" alt="Sponsorship"/>
</a>


</div>

## Features

- Drop-in replacement for `boto3.session.Session`
- Supports automatic credential refresh methods for various AWS services:
  - STS
  - ECS
- Supports custom authentication methods for complicated authentication flows
- Natively supports all parameters supported by `boto3.session.Session`
- [Tested](https://github.com/michaelthomasletts/boto3-refresh-session/tree/main/tests), [documented](https://michaelthomasletts.github.io/boto3-refresh-session/index.html), and [published to PyPI](https://pypi.org/project/boto3-refresh-session/)
- Future releases will include support for EC2, IoT, SSO, and OIDC

## Recognition, Adoption, and Testimonials

[Featured in TL;DR Sec.](https://tldrsec.com/p/tldr-sec-282)

[Featured in CloudSecList.](https://cloudseclist.com/issues/issue-290)

Recognized during AWS Community Day Midwest on June 5th, 2025.

A testimonial from a Cyber Security Engineer at a FAANG company:

> _Most of my work is on tooling related to AWS security, so I'm pretty choosy about boto3 credentials-adjacent code. I often opt to just write this sort of thing myself so I at least know that I can reason about it. But I found boto3-refresh-session to be very clean and intuitive [...] We're using the RefreshableSession class as part of a client cache construct [...] We're using AWS Lambda to perform lots of operations across several regions in hundreds of accounts, over and over again, all day every day. And it turns out that there's a surprising amount of overhead to creating boto3 clients (mostly deserializing service definition json), so we can run MUCH more efficiently if we keep a cache of clients, all equipped with automatically refreshing sessions._

## Installation

```bash
pip install boto3-refresh-session
```

## Usage (STS)

Most users use AWS STS to assume an IAM role and return a set of temporary security credentials. boto3-refresh-session can be used to ensure those temporary credentials refresh automatically.

```python
import boto3_refresh_session as brs

# you can pass all of the params normally associated with boto3.session.Session
profile_name = "<your-profile-name>"
region_name = "us-east-1"
...

# as well as all of the params associated with STS.Client.assume_role
assume_role_kwargs = {
  "RoleArn": "<your-role-arn>",
  "RoleSessionName": "<your-role-session-name>",
  "DurationSeconds": "<your-selection>",
  ...
}

# as well as all of the params associated with STS.Client, except for 'service_name'
sts_client_kwargs = {
  "region_name": region_name,
  ...
}

# basic initialization of boto3.session.Session
session = brs.RefreshableSession(
  assume_role_kwargs=assume_role_kwargs, # required
  sts_client_kwargs=sts_client_kwargs,
  region_name=region_name,
  profile_name=profile_name,
  ...
)
```

## Usage (ECS)

You can use boto3-refresh-session in an ECS container to automatically refresh temporary security credentials.

```python
session = RefreshableSession(
  method="ecs", 
  region_name=region_name, 
  profile_name=profile_name,
  ...
)
```

## Usage (Custom)

If you have a highly sophisticated, novel, or idiosyncratic authentication flow not included in boto3-refresh-session then you will need to provide your own custom temporary credentials callable object. `RefreshableSession` accepts custom credentials callable objects, as shown below.

```python
# create (or import) your custom credential method
def your_custom_credential_getter(...):
    ...
    return {
        "access_key": ...,
        "secret_key": ...,
        "token": ...,
        "expiry_time": ...,
    }

# and pass it to RefreshableSession
session = RefreshableSession(
    method="custom",
    custom_credentials_method=your_custom_credential_getter,
    custom_credentials_method_args=...,
    region_name=region_name,
    profile_name=profile_name,
    ...
)
```
            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/michaelthomasletts/boto3-refresh-session",
    "name": "boto3-refresh-session",
    "maintainer": "Michael Letts",
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": "lettsmt@gmail.com",
    "keywords": "boto3, botocore, aws, sts, ecs, credentials, token, refresh",
    "author": "Mike Letts",
    "author_email": "lettsmt@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/3a/64/b4b3c76e2888e5c116e9f0a2714b4375b45d3b1236807f71663a03e763a9/boto3_refresh_session-1.3.18.tar.gz",
    "platform": null,
    "description": "<div align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/brs.png\" />\n</div>\n\n</br>\n\n<div align=\"center\"><em>\n  A simple Python package for refreshing the temporary security credentials in a <code>boto3.session.Session</code> object automatically.\n</em></div>\n\n</br>\n\n<div align=\"center\">\n\n  <a href=\"https://pypi.org/project/boto3-refresh-session/\">\n    <img src=\"https://img.shields.io/pypi/v/boto3-refresh-session?color=%23FF0000FF&logo=python&label=Latest%20Version\" alt=\"PyPI - Version\"/>\n  </a>\n\n  <a href=\"https://pypi.org/project/boto3-refresh-session/\">\n    <img src=\"https://img.shields.io/pypi/pyversions/boto3-refresh-session?style=pypi&color=%23FF0000FF&logo=python&label=Compatible%20Python%20Versions\" alt=\"Python Version\"/>\n  </a>\n\n  <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session/actions/workflows/push.yml\">\n    <img src=\"https://img.shields.io/github/actions/workflow/status/michaelthomasletts/boto3-refresh-session/push.yml?logo=github&color=%23FF0000FF&label=Build\" alt=\"Workflow\"/>\n  </a>\n\n  <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session/commits/main\">\n    <img src=\"https://img.shields.io/github/last-commit/michaelthomasletts/boto3-refresh-session?logo=github&color=%23FF0000FF&label=Last%20Commit\" alt=\"GitHub last commit\"/>\n  </a>\n\n  <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session/stargazers\">\n    <img src=\"https://img.shields.io/github/stars/michaelthomasletts/boto3-refresh-session?style=flat&logo=github&labelColor=555&color=FF0000&label=Stars\" alt=\"Stars\"/>\n  </a>\n\n  <a href=\"https://pypistats.org/packages/boto3-refresh-session\">\n    <img src=\"https://img.shields.io/badge/downloads-72.1K-red?logo=python&color=%23FF0000&label=Downloads%20%28with%20mirrors%29\" alt=\"Downloads with mirrors\"/>\n  </a>\n\n  <a href=\"https://pypistats.org/packages/boto3-refresh-session\">\n    <img src=\"https://img.shields.io/badge/downloads-18.1K-red?logo=python&color=%23FF0000&label=Downloads%20%28without%20mirrors%29\" alt=\"Downloads without mirrors\"/>\n  </a>  \n\n  <a href=\"https://michaelthomasletts.github.io/boto3-refresh-session/index.html\">\n    <img src=\"https://img.shields.io/badge/Official%20Documentation-\ud83d\udcd8-FF0000?style=flat&labelColor=555&logo=readthedocs\" alt=\"Documentation Badge\"/>\n  </a>\n\n  <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session\">\n    <img src=\"https://img.shields.io/badge/Source%20Code-\ud83d\udcbb-FF0000?style=flat&labelColor=555&logo=github\" alt=\"Source Code Badge\"/>\n  </a>\n\n  <a href=\"https://michaelthomasletts.github.io/boto3-refresh-session/qanda.html\">\n    <img src=\"https://img.shields.io/badge/Q%26A-\u2754-FF0000?style=flat&labelColor=555&logo=vercel&label=Q%26A\" alt=\"Q&A Badge\"/>\n  </a>\n\n  <a href=\"https://medium.com/@lettsmt/you-shouldnt-have-to-think-about-refreshing-aws-credentials-214f7cbbd83b\">\n    <img src=\"https://img.shields.io/badge/Medium%20Article-\ud83d\udcd8-FF0000?style=flat&labelColor=555&logo=readthedocs\" alt=\"Medium Article\"/>\n  </a>\n\n<a href=\"https://github.com/sponsors/michaelthomasletts\">\n  <img src=\"https://img.shields.io/badge/Sponsor%20this%20Project-\ud83d\udc99-FF0000?style=flat&labelColor=555&logo=githubsponsors\" alt=\"Sponsorship\"/>\n</a>\n\n\n</div>\n\n## Features\n\n- Drop-in replacement for `boto3.session.Session`\n- Supports automatic credential refresh methods for various AWS services:\n  - STS\n  - ECS\n- Supports custom authentication methods for complicated authentication flows\n- Natively supports all parameters supported by `boto3.session.Session`\n- [Tested](https://github.com/michaelthomasletts/boto3-refresh-session/tree/main/tests), [documented](https://michaelthomasletts.github.io/boto3-refresh-session/index.html), and [published to PyPI](https://pypi.org/project/boto3-refresh-session/)\n- Future releases will include support for EC2, IoT, SSO, and OIDC\n\n## Recognition, Adoption, and Testimonials\n\n[Featured in TL;DR Sec.](https://tldrsec.com/p/tldr-sec-282)\n\n[Featured in CloudSecList.](https://cloudseclist.com/issues/issue-290)\n\nRecognized during AWS Community Day Midwest on June 5th, 2025.\n\nA testimonial from a Cyber Security Engineer at a FAANG company:\n\n> _Most of my work is on tooling related to AWS security, so I'm pretty choosy about boto3 credentials-adjacent code. I often opt to just write this sort of thing myself so I at least know that I can reason about it. But I found boto3-refresh-session to be very clean and intuitive [...] We're using the RefreshableSession class as part of a client cache construct [...] We're using AWS Lambda to perform lots of operations across several regions in hundreds of accounts, over and over again, all day every day. And it turns out that there's a surprising amount of overhead to creating boto3 clients (mostly deserializing service definition json), so we can run MUCH more efficiently if we keep a cache of clients, all equipped with automatically refreshing sessions._\n\n## Installation\n\n```bash\npip install boto3-refresh-session\n```\n\n## Usage (STS)\n\nMost users use AWS STS to assume an IAM role and return a set of temporary security credentials. boto3-refresh-session can be used to ensure those temporary credentials refresh automatically.\n\n```python\nimport boto3_refresh_session as brs\n\n# you can pass all of the params normally associated with boto3.session.Session\nprofile_name = \"<your-profile-name>\"\nregion_name = \"us-east-1\"\n...\n\n# as well as all of the params associated with STS.Client.assume_role\nassume_role_kwargs = {\n  \"RoleArn\": \"<your-role-arn>\",\n  \"RoleSessionName\": \"<your-role-session-name>\",\n  \"DurationSeconds\": \"<your-selection>\",\n  ...\n}\n\n# as well as all of the params associated with STS.Client, except for 'service_name'\nsts_client_kwargs = {\n  \"region_name\": region_name,\n  ...\n}\n\n# basic initialization of boto3.session.Session\nsession = brs.RefreshableSession(\n  assume_role_kwargs=assume_role_kwargs, # required\n  sts_client_kwargs=sts_client_kwargs,\n  region_name=region_name,\n  profile_name=profile_name,\n  ...\n)\n```\n\n## Usage (ECS)\n\nYou can use boto3-refresh-session in an ECS container to automatically refresh temporary security credentials.\n\n```python\nsession = RefreshableSession(\n  method=\"ecs\", \n  region_name=region_name, \n  profile_name=profile_name,\n  ...\n)\n```\n\n## Usage (Custom)\n\nIf you have a highly sophisticated, novel, or idiosyncratic authentication flow not included in boto3-refresh-session then you will need to provide your own custom temporary credentials callable object. `RefreshableSession` accepts custom credentials callable objects, as shown below.\n\n```python\n# create (or import) your custom credential method\ndef your_custom_credential_getter(...):\n    ...\n    return {\n        \"access_key\": ...,\n        \"secret_key\": ...,\n        \"token\": ...,\n        \"expiry_time\": ...,\n    }\n\n# and pass it to RefreshableSession\nsession = RefreshableSession(\n    method=\"custom\",\n    custom_credentials_method=your_custom_credential_getter,\n    custom_credentials_method_args=...,\n    region_name=region_name,\n    profile_name=profile_name,\n    ...\n)\n```",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.",
    "version": "1.3.18",
    "project_urls": {
        "Documentation": "https://michaelthomasletts.github.io/boto3-refresh-session/index.html",
        "Homepage": "https://github.com/michaelthomasletts/boto3-refresh-session",
        "Repository": "https://github.com/michaelthomasletts/boto3-refresh-session"
    },
    "split_keywords": [
        "boto3",
        " botocore",
        " aws",
        " sts",
        " ecs",
        " credentials",
        " token",
        " refresh"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "bb964c8650abad9580a2be20dd4a7badd2a57900c56eed6badd6d862a141e6eb",
                "md5": "01eafbaae12b2a57efebbae91ef39599",
                "sha256": "045801c97074f71b4b516ddca0cb7948688f8dc48f6a9206a9a2169399567634"
            },
            "downloads": -1,
            "filename": "boto3_refresh_session-1.3.18-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "01eafbaae12b2a57efebbae91ef39599",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 11983,
            "upload_time": "2025-07-12T11:45:54",
            "upload_time_iso_8601": "2025-07-12T11:45:54.895631Z",
            "url": "https://files.pythonhosted.org/packages/bb/96/4c8650abad9580a2be20dd4a7badd2a57900c56eed6badd6d862a141e6eb/boto3_refresh_session-1.3.18-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "3a64b4b3c76e2888e5c116e9f0a2714b4375b45d3b1236807f71663a03e763a9",
                "md5": "b86127dcd266e39b662caf0807acb9b2",
                "sha256": "a10379aa4aee3a216dd881df1ae675d0d27fb72dce970c446f1d5155bd9765c3"
            },
            "downloads": -1,
            "filename": "boto3_refresh_session-1.3.18.tar.gz",
            "has_sig": false,
            "md5_digest": "b86127dcd266e39b662caf0807acb9b2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 10523,
            "upload_time": "2025-07-12T11:45:56",
            "upload_time_iso_8601": "2025-07-12T11:45:56.068323Z",
            "url": "https://files.pythonhosted.org/packages/3a/64/b4b3c76e2888e5c116e9f0a2714b4375b45d3b1236807f71663a03e763a9/boto3_refresh_session-1.3.18.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-12 11:45:56",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "michaelthomasletts",
    "github_project": "boto3-refresh-session",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "boto3-refresh-session"
}
        
Elapsed time: 0.53581s