<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="py_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="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://pepy.tech/projects/boto3-refresh-session">
<img
src="https://img.shields.io/endpoint?url=https%3A%2F%2Fmichaelthomasletts.github.io%2Fpepy-stats%2Fboto3-refresh-session.json&style=flat&logo=python&labelColor=555&color=FF0000"
alt="downloads"
/>
</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"
/>
</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="github"
/>
</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="qanda"
/>
</a>
<a href="https://michaelthomasletts.github.io/blog/brs-rationale/">
<img
src="https://img.shields.io/badge/Blog%20Post-📘-FF0000?style=flat&labelColor=555&logo=readthedocs"
alt="blog"
/>
</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 for:
- **STS**
- **IoT Core**
- X.509 certificates w/ role aliases over mTLS (PEM files and PKCS#11)
- MQTT actions are available!
- Custom authentication methods
- 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 IoT (coming soon)
## 😌 Recognition 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
<details>
<summary><strong>Core Concepts (click to expand)</strong></summary>
### Core Concepts
1. `RefreshableSession` is the intended interface for using `boto3-refresh-session`. Whether you're using this package to refresh temporary credentials returned by STS, the IoT credential provider (which is really just STS, but I digress), or some custom authentication or credential provider, `RefreshableSession` is where you *ought to* be working when using `boto3-refresh-session`.
2. *You can use all of the same keyword parameters normally associated with `boto3.session.Session`!* For instance, suppose you want to pass `region_name` to `RefreshableSession` as a parameter, whereby it's passed to `boto3.session.Session`. That's perfectly fine! Just pass it like you normally would when initializing `boto3.session.Session`. These keyword parameters are *completely optional*, though. If you're confused, the main idea to remember is this: if initializing `boto3.session.Session` *requires* a particular keyword parameter then pass it to `RefreshableSession`; if not, don't worry about it.
3. To tell `RefreshableSession` which AWS service you're working with for authentication and credential retrieval purposes (STS vs. IoT vs. some custom credential provider), you'll need to pass a `method` parameter to `RefreshableSession`. Since the `service_name` namespace is already occupied by `boto3.sesssion.Session`, [`boto3-refresh-session` uses `method` instead of "service" so as to avoid confusion](https://github.com/michaelthomasletts/boto3-refresh-session/blob/04acb2adb34e505c4dc95711f6b2f97748a2a489/boto3_refresh_session/utils/typing.py#L40). If you're using `RefreshableSession` for STS, however, then `method` is set to `"sts"` by default. You don't need to pass the `method` keyword argument in that case.
4. Using `RefreshableSession` for STS, IoT, or custom flows requires different keyword parameters that are unique to those particular methods. For instance, `STSRefreshableSession`, which is the engine for STS in `boto3-refresh-session`, requires `assume_role_kwargs` and optionally allows `sts_client_kwargs` whereas `CustomRefreshableSession` and `IoTX509RefreshableSession` do not. To familiarize yourself with the keyword parameters for each method, check the documentation for each of those engines [in the Refresh Strategies section here](https://michaelthomasletts.com/boto3-refresh-session/modules/index.html).
5. Irrespective of whatever `method` you pass as a keyword parameter, `RefreshableSession` accepts a keyword parameter named `defer_refresh`. Basically, this boolean tells `boto3-refresh-session` either to refresh credentials *the moment they expire* or to *wait until credentials are explicitly needed*. If you are working in a low-latency environment then `defer_refresh = False` might be helpful. For most users, however, `defer_refresh = True` is most desirable. For that reason, `defer_refresh = True` is the default value. Most users, therefore, should not concern themselves too much with this feature.
6. Some developers struggle to imagine where `boto3-refresh-session` might be helpful. To figure out if `boto3-refresh-session` is for your use case, or whether `credential_process` satisfies your needs, check out [this blog post](https://michaelthomasletts.com/blog/brs-rationale/). `boto3-refresh-session` is not for every developer or use-case; it is a niche tool.
</details>
<details>
<summary><strong>Clients and Resources (click to expand)</strong></summary>
### Clients and Resources
Most developers who use `boto3` interact primarily with `boto3.client` or `boto3.resource` instead of `boto3.session.Session`. But many developers may not realize that `boto3.session.Session` belies `boto3.client` and `boto3.resource`! In fact, that's precisely what makes `boto3-refresh-session` possible!
To use the `boto3.client` or `boto3.resource` interface, but with the benefits of `boto3-refresh-session`, you have a few options!
In the following examples, let's assume you want to use STS for retrieving temporary credentials for the sake of simplicity. Let's also focus specifically on `client`. Switching to `resource` follows the same exact idioms as below, except that `client` must be switched to `resource` in the pseudo-code, obviously. If you are not sure how to use `RefreshableSession` for STS (or custom auth flows) then check the usage instructions in the following sections!
##### `RefreshableSession.client` (Recommended)
So long as you reuse the same `session` object when creating `client` and `resource` objects, this approach can be used everywhere in your code. It is very simple and straight-forward!
```python
from boto3_refresh_session import RefreshableSession
assume_role_kwargs = {
"RoleArn": "<your-role-arn>",
"RoleSessionName": "<your-role-session-name>",
"DurationSeconds": "<your-selection>",
...
}
session = RefreshableSession(assume_role_kwargs=assume_role_kwargs)
s3 = session.client("s3")
```
##### `DEFAULT_SESSION`
This technique can be helpful if you want to use the same instance of `RefreshableSession` everywhere in your code without reference to `boto3_refresh_session`!
```python
from boto3 import DEFAULT_SESSION, client
from boto3_refresh_session import RefreshableSession
assume_role_kwargs = {
"RoleArn": "<your-role-arn>",
"RoleSessionName": "<your-role-session-name>",
"DurationSeconds": "<your-selection>",
...
}
DEFAULT_SESSION = RefreshableSession(assume_role_kwargs=assume_role_kwargs)
s3 = client("s3")
```
##### `botocore_session`
```python
from boto3 import client
from boto3_refresh_session import RefreshableSession
assume_role_kwargs = {
"RoleArn": "<your-role-arn>",
"RoleSessionName": "<your-role-session-name>",
"DurationSeconds": "<your-selection>",
...
}
s3 = client(
service_name="s3",
botocore_session=RefreshableSession(assume_role_kwargs=assume_role_kwargs)
)
```
</details>
<details>
<summary><strong>STS (click to expand)</strong></summary>
### STS
Most developers 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. For additional information on the exact parameters that `RefreshableSession` takes for STS, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/sts.py).
```python
import boto3_refresh_session as brs
# OPTIONAL - you can pass all of the params normally associated with boto3.session.Session
profile_name = "<your-profile-name>"
region_name = "us-east-1"
...
# REQUIRED - 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>",
...
}
# OPTIONAL - 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, # optional
region_name=region_name, # optional
profile_name=profile_name, # optional
... # misc. params for boto3.session.Session
)
```
</details>
<details>
<summary><strong>Custom Authentication Flows (click to expand)</strong></summary>
### 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. For additional information on the exact parameters that `RefreshableSession` takes for custom authentication flows, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/custom.py).
```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", # required
custom_credentials_method=your_custom_credential_getter, # required
custom_credentials_method_args=..., # optional
region_name=region_name, # optional
profile_name=profile_name, # optional
... # misc. params for boto3.session.Session
)
```
</details>
<details>
<summary><strong>IoT Core X.509 (click to expand)</strong></summary>
### IoT Core X.509
AWS IoT Core can vend temporary AWS credentials through the **credentials provider** when you connect with an X.509 certificate and a **role alias**. `boto3-refresh-session` makes this flow seamless by automatically refreshing credentials over **mTLS**.
For additional information on the exact parameters that `IOTX509RefreshableSession` takes, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/iot/x509.py).
### PEM file
```python
import boto3_refresh_session as brs
# PEM certificate + private key example
session = brs.RefreshableSession(
method="iot",
endpoint="<your-credentials-endpoint>.credentials.iot.<region>.amazonaws.com",
role_alias="<your-role-alias>",
certificate="/path/to/certificate.pem",
private_key="/path/to/private-key.pem",
thing_name="<your-thing-name>", # optional, if used in policies
duration_seconds=3600, # optional, capped by role alias
region_name="us-east-1",
)
# Now you can use the session like any boto3 session
s3 = session.client("s3")
print(s3.list_buckets())
```
### PKCS#11
```python
session = brs.RefreshableSession(
method="iot",
endpoint="<your-credentials-endpoint>.credentials.iot.<region>.amazonaws.com",
role_alias="<your-role-alias>",
certificate="/path/to/certificate.pem",
pkcs11={
"pkcs11_lib": "/usr/local/lib/softhsm/libsofthsm2.so",
"user_pin": "1234",
"slot_id": 0,
"token_label": "MyToken",
"private_key_label": "MyKey",
},
thing_name="<your-thing-name>",
region_name="us-east-1",
)
```
### MQTT
After initializing a session object, you can can begin making actions with MQTT using the [mqtt method](https://github.com/michaelthomasletts/boto3-refresh-session/blob/deb68222925bf648f26e878ed4bc24b45317c7db/boto3_refresh_session/methods/iot/x509.py#L367)! You can reuse the same certificate, private key, et al as that used to initialize `RefreshableSession`. Or, alternatively, you can provide separate PKCS#11 or certificate information, whether those be file paths or bytes values. Either way, at a minimum, you will need to provide the endpoint and client identifier (i.e. thing name).
```python
from awscrt.mqtt.QoS import AT_LEAST_ONCE
conn = session.mqtt(
endpoint="<your endpoint>-ats.iot.<region>.amazonaws.com",
client_id="<your thing name or client ID>",
)
conn.connect()
conn.connect().result()
conn.publish(topic="foo/bar", payload=b"hi", qos=AT_LEAST_ONCE)
conn.disconnect().result()
```
</details>
## ⚠️ Changes
Browse through the various changes to `boto3-refresh-session` over time.
#### 😥 v3.0.0
**The changes introduced by v3.0.0 will not impact ~99% of users** who generally interact with `boto3-refresh-session` by only `RefreshableSession`, *which is the intended usage for this package after all.*
Advanced users, however, particularly those using low-level objects such as `BaseRefreshableSession | refreshable_session | BRSSession | utils.py`, may experience breaking changes.
Please review [this PR](https://github.com/michaelthomasletts/boto3-refresh-session/pull/75) for additional details.
#### ✂️ v4.0.0
The `ecs` module has been dropped. For additional details and rationale, please review [this PR](https://github.com/michaelthomasletts/boto3-refresh-session/pull/78).
#### 😛 v5.0.0
Support for IoT Core via X.509 certificate-based authentication (over HTTPS) is now available!
#### ➕ v5.1.0
MQTT support added for IoT Core via X.509 certificate-based authentication.
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, credentials, token, refresh, iot, x509, mqtt",
"author": "Mike Letts",
"author_email": "lettsmt@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/de/98/af221d2bd13933b999970c92a350f1bda496bbf3312c1398034411655f8d/boto3_refresh_session-5.1.6.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 \n src=\"https://img.shields.io/pypi/v/boto3-refresh-session?color=%23FF0000FF&logo=python&label=Latest%20Version\"\n alt=\"pypi_version\"\n />\n </a>\n\n <a href=\"https://pypi.org/project/boto3-refresh-session/\">\n <img \n src=\"https://img.shields.io/pypi/pyversions/boto3-refresh-session?style=pypi&color=%23FF0000FF&logo=python&label=Compatible%20Python%20Versions\" \n alt=\"py_version\"\n />\n </a>\n\n <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session/actions/workflows/push.yml\">\n <img \n src=\"https://img.shields.io/github/actions/workflow/status/michaelthomasletts/boto3-refresh-session/push.yml?logo=github&color=%23FF0000FF&label=Build\" \n alt=\"workflow\"\n />\n </a>\n\n <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session/commits/main\">\n <img \n src=\"https://img.shields.io/github/last-commit/michaelthomasletts/boto3-refresh-session?logo=github&color=%23FF0000FF&label=Last%20Commit\" \n alt=\"last_commit\"\n />\n </a>\n\n <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session/stargazers\">\n <img \n src=\"https://img.shields.io/github/stars/michaelthomasletts/boto3-refresh-session?style=flat&logo=github&labelColor=555&color=FF0000&label=Stars\" \n alt=\"stars\"\n />\n </a>\n\n<a href=\"https://pepy.tech/projects/boto3-refresh-session\">\n <img\n src=\"https://img.shields.io/endpoint?url=https%3A%2F%2Fmichaelthomasletts.github.io%2Fpepy-stats%2Fboto3-refresh-session.json&style=flat&logo=python&labelColor=555&color=FF0000\"\n alt=\"downloads\"\n />\n</a>\n\n\n <a href=\"https://michaelthomasletts.github.io/boto3-refresh-session/index.html\">\n <img \n src=\"https://img.shields.io/badge/Official%20Documentation-\ud83d\udcd8-FF0000?style=flat&labelColor=555&logo=readthedocs\" \n alt=\"documentation\"\n />\n </a>\n\n <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session\">\n <img \n src=\"https://img.shields.io/badge/Source%20Code-\ud83d\udcbb-FF0000?style=flat&labelColor=555&logo=github\" \n alt=\"github\"\n />\n </a>\n\n <a href=\"https://michaelthomasletts.github.io/boto3-refresh-session/qanda.html\">\n <img \n src=\"https://img.shields.io/badge/Q%26A-\u2754-FF0000?style=flat&labelColor=555&logo=vercel&label=Q%26A\" \n alt=\"qanda\"\n />\n </a>\n\n <a href=\"https://michaelthomasletts.github.io/blog/brs-rationale/\">\n <img \n src=\"https://img.shields.io/badge/Blog%20Post-\ud83d\udcd8-FF0000?style=flat&labelColor=555&logo=readthedocs\" \n alt=\"blog\"\n />\n </a>\n\n<a href=\"https://github.com/sponsors/michaelthomasletts\">\n <img \n src=\"https://img.shields.io/badge/Sponsor%20this%20Project-\ud83d\udc99-FF0000?style=flat&labelColor=555&logo=githubsponsors\" \n alt=\"sponsorship\"\n />\n</a>\n\n</div>\n\n## \ud83d\ude1b Features\n\n- Drop-in replacement for `boto3.session.Session`\n- Supports automatic credential refresh for: \n - **STS**\n - **IoT Core** \n - X.509 certificates w/ role aliases over mTLS (PEM files and PKCS#11)\n - MQTT actions are available!\n - Custom authentication methods\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 IoT (coming soon)\n\n## \ud83d\ude0c Recognition 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## \ud83d\udcbb Installation\n\n```bash\npip install boto3-refresh-session\n```\n\n## \ud83d\udcdd Usage\n\n<details>\n <summary><strong>Core Concepts (click to expand)</strong></summary>\n\n ### Core Concepts\n\n 1. `RefreshableSession` is the intended interface for using `boto3-refresh-session`. Whether you're using this package to refresh temporary credentials returned by STS, the IoT credential provider (which is really just STS, but I digress), or some custom authentication or credential provider, `RefreshableSession` is where you *ought to* be working when using `boto3-refresh-session`.\n\n 2. *You can use all of the same keyword parameters normally associated with `boto3.session.Session`!* For instance, suppose you want to pass `region_name` to `RefreshableSession` as a parameter, whereby it's passed to `boto3.session.Session`. That's perfectly fine! Just pass it like you normally would when initializing `boto3.session.Session`. These keyword parameters are *completely optional*, though. If you're confused, the main idea to remember is this: if initializing `boto3.session.Session` *requires* a particular keyword parameter then pass it to `RefreshableSession`; if not, don't worry about it.\n\n 3. To tell `RefreshableSession` which AWS service you're working with for authentication and credential retrieval purposes (STS vs. IoT vs. some custom credential provider), you'll need to pass a `method` parameter to `RefreshableSession`. Since the `service_name` namespace is already occupied by `boto3.sesssion.Session`, [`boto3-refresh-session` uses `method` instead of \"service\" so as to avoid confusion](https://github.com/michaelthomasletts/boto3-refresh-session/blob/04acb2adb34e505c4dc95711f6b2f97748a2a489/boto3_refresh_session/utils/typing.py#L40). If you're using `RefreshableSession` for STS, however, then `method` is set to `\"sts\"` by default. You don't need to pass the `method` keyword argument in that case.\n\n 4. Using `RefreshableSession` for STS, IoT, or custom flows requires different keyword parameters that are unique to those particular methods. For instance, `STSRefreshableSession`, which is the engine for STS in `boto3-refresh-session`, requires `assume_role_kwargs` and optionally allows `sts_client_kwargs` whereas `CustomRefreshableSession` and `IoTX509RefreshableSession` do not. To familiarize yourself with the keyword parameters for each method, check the documentation for each of those engines [in the Refresh Strategies section here](https://michaelthomasletts.com/boto3-refresh-session/modules/index.html).\n\n 5. Irrespective of whatever `method` you pass as a keyword parameter, `RefreshableSession` accepts a keyword parameter named `defer_refresh`. Basically, this boolean tells `boto3-refresh-session` either to refresh credentials *the moment they expire* or to *wait until credentials are explicitly needed*. If you are working in a low-latency environment then `defer_refresh = False` might be helpful. For most users, however, `defer_refresh = True` is most desirable. For that reason, `defer_refresh = True` is the default value. Most users, therefore, should not concern themselves too much with this feature.\n\n 6. Some developers struggle to imagine where `boto3-refresh-session` might be helpful. To figure out if `boto3-refresh-session` is for your use case, or whether `credential_process` satisfies your needs, check out [this blog post](https://michaelthomasletts.com/blog/brs-rationale/). `boto3-refresh-session` is not for every developer or use-case; it is a niche tool. \n\n</details>\n\n<details>\n <summary><strong>Clients and Resources (click to expand)</strong></summary>\n\n ### Clients and Resources\n\n Most developers who use `boto3` interact primarily with `boto3.client` or `boto3.resource` instead of `boto3.session.Session`. But many developers may not realize that `boto3.session.Session` belies `boto3.client` and `boto3.resource`! In fact, that's precisely what makes `boto3-refresh-session` possible!\n\n To use the `boto3.client` or `boto3.resource` interface, but with the benefits of `boto3-refresh-session`, you have a few options! \n \n In the following examples, let's assume you want to use STS for retrieving temporary credentials for the sake of simplicity. Let's also focus specifically on `client`. Switching to `resource` follows the same exact idioms as below, except that `client` must be switched to `resource` in the pseudo-code, obviously. If you are not sure how to use `RefreshableSession` for STS (or custom auth flows) then check the usage instructions in the following sections!\n\n ##### `RefreshableSession.client` (Recommended)\n\n So long as you reuse the same `session` object when creating `client` and `resource` objects, this approach can be used everywhere in your code. It is very simple and straight-forward!\n\n ```python\n from boto3_refresh_session import RefreshableSession\n\n assume_role_kwargs = {\n \"RoleArn\": \"<your-role-arn>\",\n \"RoleSessionName\": \"<your-role-session-name>\",\n \"DurationSeconds\": \"<your-selection>\",\n ...\n }\n session = RefreshableSession(assume_role_kwargs=assume_role_kwargs)\n s3 = session.client(\"s3\")\n ``` \n\n ##### `DEFAULT_SESSION`\n\n This technique can be helpful if you want to use the same instance of `RefreshableSession` everywhere in your code without reference to `boto3_refresh_session`!\n\n ```python\n from boto3 import DEFAULT_SESSION, client\n from boto3_refresh_session import RefreshableSession\n\n assume_role_kwargs = {\n \"RoleArn\": \"<your-role-arn>\",\n \"RoleSessionName\": \"<your-role-session-name>\",\n \"DurationSeconds\": \"<your-selection>\",\n ...\n }\n DEFAULT_SESSION = RefreshableSession(assume_role_kwargs=assume_role_kwargs)\n s3 = client(\"s3\")\n ```\n\n ##### `botocore_session`\n\n ```python\n from boto3 import client\n from boto3_refresh_session import RefreshableSession\n\n assume_role_kwargs = {\n \"RoleArn\": \"<your-role-arn>\",\n \"RoleSessionName\": \"<your-role-session-name>\",\n \"DurationSeconds\": \"<your-selection>\",\n ...\n }\n s3 = client(\n service_name=\"s3\",\n botocore_session=RefreshableSession(assume_role_kwargs=assume_role_kwargs)\n )\n ``` \n\n </details>\n\n<details>\n <summary><strong>STS (click to expand)</strong></summary>\n\n ### STS\n\n Most developers 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. For additional information on the exact parameters that `RefreshableSession` takes for STS, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/sts.py).\n\n ```python\n import boto3_refresh_session as brs\n\n # OPTIONAL - you can pass all of the params normally associated with boto3.session.Session\n profile_name = \"<your-profile-name>\"\n region_name = \"us-east-1\"\n ...\n\n # REQUIRED - as well as all of the params associated with STS.Client.assume_role\n assume_role_kwargs = {\n \"RoleArn\": \"<your-role-arn>\",\n \"RoleSessionName\": \"<your-role-session-name>\",\n \"DurationSeconds\": \"<your-selection>\",\n ...\n }\n\n # OPTIONAL - as well as all of the params associated with STS.Client, except for 'service_name'\n sts_client_kwargs = {\n \"region_name\": region_name,\n ...\n }\n\n # basic initialization of boto3.session.Session\n session = brs.RefreshableSession(\n assume_role_kwargs=assume_role_kwargs, # required\n sts_client_kwargs=sts_client_kwargs, # optional\n region_name=region_name, # optional\n profile_name=profile_name, # optional\n ... # misc. params for boto3.session.Session\n )\n ```\n\n</details>\n\n<details>\n <summary><strong>Custom Authentication Flows (click to expand)</strong></summary>\n\n ### Custom\n\n 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. For additional information on the exact parameters that `RefreshableSession` takes for custom authentication flows, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/custom.py).\n\n ```python\n # create (or import) your custom credential method\n def 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\n session = RefreshableSession(\n method=\"custom\", # required\n custom_credentials_method=your_custom_credential_getter, # required\n custom_credentials_method_args=..., # optional\n region_name=region_name, # optional\n profile_name=profile_name, # optional\n ... # misc. params for boto3.session.Session\n )\n ```\n\n</details>\n\n<details>\n <summary><strong>IoT Core X.509 (click to expand)</strong></summary>\n\n ### IoT Core X.509\n\n AWS IoT Core can vend temporary AWS credentials through the **credentials provider** when you connect with an X.509 certificate and a **role alias**. `boto3-refresh-session` makes this flow seamless by automatically refreshing credentials over **mTLS**.\n\n For additional information on the exact parameters that `IOTX509RefreshableSession` takes, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/iot/x509.py).\n\n ### PEM file\n\n ```python\n import boto3_refresh_session as brs\n\n # PEM certificate + private key example\n session = brs.RefreshableSession(\n method=\"iot\",\n endpoint=\"<your-credentials-endpoint>.credentials.iot.<region>.amazonaws.com\",\n role_alias=\"<your-role-alias>\",\n certificate=\"/path/to/certificate.pem\",\n private_key=\"/path/to/private-key.pem\",\n thing_name=\"<your-thing-name>\", # optional, if used in policies\n duration_seconds=3600, # optional, capped by role alias\n region_name=\"us-east-1\",\n )\n\n # Now you can use the session like any boto3 session\n s3 = session.client(\"s3\")\n print(s3.list_buckets())\n ```\n\n ### PKCS#11\n\n ```python\n session = brs.RefreshableSession(\n method=\"iot\",\n endpoint=\"<your-credentials-endpoint>.credentials.iot.<region>.amazonaws.com\",\n role_alias=\"<your-role-alias>\",\n certificate=\"/path/to/certificate.pem\",\n pkcs11={\n \"pkcs11_lib\": \"/usr/local/lib/softhsm/libsofthsm2.so\",\n \"user_pin\": \"1234\",\n \"slot_id\": 0,\n \"token_label\": \"MyToken\",\n \"private_key_label\": \"MyKey\",\n },\n thing_name=\"<your-thing-name>\",\n region_name=\"us-east-1\",\n )\n ```\n\n ### MQTT\n\n After initializing a session object, you can can begin making actions with MQTT using the [mqtt method](https://github.com/michaelthomasletts/boto3-refresh-session/blob/deb68222925bf648f26e878ed4bc24b45317c7db/boto3_refresh_session/methods/iot/x509.py#L367)! You can reuse the same certificate, private key, et al as that used to initialize `RefreshableSession`. Or, alternatively, you can provide separate PKCS#11 or certificate information, whether those be file paths or bytes values. Either way, at a minimum, you will need to provide the endpoint and client identifier (i.e. thing name).\n\n ```python\n from awscrt.mqtt.QoS import AT_LEAST_ONCE\n conn = session.mqtt(\n endpoint=\"<your endpoint>-ats.iot.<region>.amazonaws.com\",\n client_id=\"<your thing name or client ID>\",\n )\n conn.connect()\n conn.connect().result()\n conn.publish(topic=\"foo/bar\", payload=b\"hi\", qos=AT_LEAST_ONCE)\n conn.disconnect().result()\n ```\n\n</details>\n\n## \u26a0\ufe0f Changes\n\nBrowse through the various changes to `boto3-refresh-session` over time.\n\n#### \ud83d\ude25 v3.0.0\n\n**The changes introduced by v3.0.0 will not impact ~99% of users** who generally interact with `boto3-refresh-session` by only `RefreshableSession`, *which is the intended usage for this package after all.* \n\nAdvanced users, however, particularly those using low-level objects such as `BaseRefreshableSession | refreshable_session | BRSSession | utils.py`, may experience breaking changes. \n\nPlease review [this PR](https://github.com/michaelthomasletts/boto3-refresh-session/pull/75) for additional details.\n\n#### \u2702\ufe0f v4.0.0\n\nThe `ecs` module has been dropped. For additional details and rationale, please review [this PR](https://github.com/michaelthomasletts/boto3-refresh-session/pull/78).\n\n#### \ud83d\ude1b v5.0.0\n\nSupport for IoT Core via X.509 certificate-based authentication (over HTTPS) is now available!\n\n#### \u2795 v5.1.0\n\nMQTT support added for IoT Core via X.509 certificate-based authentication.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.",
"version": "5.1.6",
"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",
" credentials",
" token",
" refresh",
" iot",
" x509",
" mqtt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7de270a0767b057f90fec6300d935992ce074668835ce6303e8f87c4ba1fce4c",
"md5": "116e85558ca223db603c1dfac23aa315",
"sha256": "88ec73769410187ea94462354906012a4b3e73656808d4670844b7ce603c6930"
},
"downloads": -1,
"filename": "boto3_refresh_session-5.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "116e85558ca223db603c1dfac23aa315",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 23264,
"upload_time": "2025-09-14T10:38:26",
"upload_time_iso_8601": "2025-09-14T10:38:26.753060Z",
"url": "https://files.pythonhosted.org/packages/7d/e2/70a0767b057f90fec6300d935992ce074668835ce6303e8f87c4ba1fce4c/boto3_refresh_session-5.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "de98af221d2bd13933b999970c92a350f1bda496bbf3312c1398034411655f8d",
"md5": "91e03f3b81bf92e18ddc016311659ce7",
"sha256": "6cd912d1c94898c2b4cb4779c27fdbadb90608ac91350d9ad70896c53a1cf55d"
},
"downloads": -1,
"filename": "boto3_refresh_session-5.1.6.tar.gz",
"has_sig": false,
"md5_digest": "91e03f3b81bf92e18ddc016311659ce7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 22701,
"upload_time": "2025-09-14T10:38:28",
"upload_time_iso_8601": "2025-09-14T10:38:28.090919Z",
"url": "https://files.pythonhosted.org/packages/de/98/af221d2bd13933b999970c92a350f1bda496bbf3312c1398034411655f8d/boto3_refresh_session-5.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 10:38:28",
"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"
}
JSON
