# boto3-assume
`boto3-assume` has one simple goal. Easily create `boto3`/`aioboto3` assume role sessions with automatic credential refreshing.
## Installation
Install with pip:
```text
$ pip install boto3-assume
```
> **NOTE** - It currently doesn't come with `boto3` or `aioboto3` , so you need install to one or both as needed.
## Tutorial
There are only 2 functions `assume_role_session` and `assume_role_aio_session`
For `boto3`:
```python
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`:
```python
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](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html#boto3.session.Session.client), and for the [assume_role](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sts/client/assume_role.html) call.
> **NOTE**: The "sts" service is already specified for the client.
`RoleArn` and `RoleSessionName` are used in the assume role call.
```python
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.
```text
(venv) $ pip install -e .[dev,all]
```
[nox](https://nox.thea.codes/en/stable/) is used to manage various dev functions.
Start with
```text
(venv) $ nox --help
```
[pyenv](https://github.com/pyenv/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:
```text
(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](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
<!--
## [Unreleased] - YYYY-MM-DD
### Added
### Changed
### Deprecated
### Removed
### Fixed
### Security
-->
## [0.1.2] - 2024-05-18
### Removed
- `boto3` and `aioboto3` package extras. They didn't work and weren't documented correctly.
### Fixed
- `datetime.datetime.utcnow()` deprecation in tests for python 3.12
## [0.1.1] - 2023-06-28
### Fixed
- Formatting for Changelog, README
## [0.1.0] - 2023-06-28
Initial Release.
Raw data
{
"_id": null,
"home_page": "https://github.com/btemplep/boto3-assume",
"name": "boto3-assume",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "aio, aioboto3, aiobotocore, assume, async, asyncio, aws, boto3, botocore, credentials, creds, iam, refresh, refreshable, role, sdk",
"author": "Brandon Temple Paul",
"author_email": "btemplepgit@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f6/c9/bb3790c1722e897a3e7683e72a01d7b3a38bfa3ea35a3b899a4c201949a4/boto3_assume-0.1.2.tar.gz",
"platform": null,
"description": "# boto3-assume\n\n\n`boto3-assume` has one simple goal. Easily create `boto3`/`aioboto3` assume role sessions with automatic credential refreshing.\n\n\n## Installation\n\nInstall with pip:\n\n```text\n$ pip install boto3-assume\n```\n\n> **NOTE** - It currently doesn't come with `boto3` or `aioboto3` , so you need install to one or both as needed.\n\n\n## Tutorial\n\nThere are only 2 functions `assume_role_session` and `assume_role_aio_session`\n\nFor `boto3`:\n\n```python\nimport boto3\nfrom boto3_assume import assume_role_session\n\nassume_session = assume_role_session(\n source_session=boto3.Session(), # You must pass in a boto3 session that automatically refreshes!\n RoleArn=\"arn:aws:iam::123412341234:role/my_role\",\n RoleSessionName=\"my-role-session\"\n)\n\n# Create clients, and their credentials will auto-refresh when expired!\nsts_client = assume_session.client(\"sts\", region_name=\"us-east-1\")\nprint(sts_client.get_caller_identity())\n# {\n# \"UserId\": \"EXAMPLEID\", \n# \"Account\": \"123412341234\", \n# \"Arn\": \"arn:aws:sts::123412341234:role/my_role\", \n# \"ResponseMetadata\": {\n# \"RequestId\": \"asdfqwfqwfasdfasdfasfsdf\", \n# \"HTTPStatusCode\": 200, \n# \"HTTPHeaders\": {\n# \"server\": \"amazon.com\", \n# \"date\": \"Tue, 27 Jun 2023 00:00:00 GMT\"\n# }, \n# \"RetryAttempts\": 0\n# }\n# }\n```\n\nFor `aioboto3`:\n\n```python\nimport asyncio\n\nimport aioboto3\nfrom boto3_assume import assume_role_aio_session\n\n# since this uses \"Deferred\" credentials you don't need to call this within a coroutine or context manager\nassume_session = assume_role_session(\n source_session=aioboto3.Session(), # You must pass in an aioboto3 session that automatically refreshes!\n RoleArn=\"arn:aws:iam::123412341234:role/my_role\",\n RoleSessionName=\"my-role-session\"\n)\n\nasync def main():\n # Create clients, and their credentials will auto-refresh when expired!\n async with assume_session.client(\"sts\", region_name=\"us-east-1\") as sts_client:\n print(await sts_client.get_caller_identity())\n # {\n # \"UserId\": \"EXAMPLEID\", \n # \"Account\": \"123412341234\", \n # \"Arn\": \"arn:aws:sts::123412341234:role/my_role\", \n # \"ResponseMetadata\": {\n # \"RequestId\": \"asdfqwfqwfasdfasdfasfsdf\", \n # \"HTTPStatusCode\": 200, \n # \"HTTPHeaders\": {\n # \"server\": \"amazon.com\", \n # \"date\": \"Tue, 27 Jun 2023 00:00:00 GMT\"\n # }, \n # \"RetryAttempts\": 0\n # }\n # }\n\nasyncio.run(main())\n```\n\nUnder the hood a `boto3`/`aioboto3` sts client will be created and `assume_role` called to get/refresh credentials.\n\nIf you want you can also specify extra kwargs for the [sts client](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html#boto3.session.Session.client), and for the [assume_role](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sts/client/assume_role.html) call.\n\n\n> **NOTE**: The \"sts\" service is already specified for the client. \n`RoleArn` and `RoleSessionName` are used in the assume role call. \n\n```python\nimport boto3\nfrom boto3_assume import assume_role_session\nfrom botocore.config import Config\n\nassume_session = assume_role_session(\n source_session=boto3.Session(), # You must pass in a boto3 session that automatically refreshes!\n RoleArn=\"arn:aws:iam::123412341234:role/my_role\",\n RoleSessionName=\"my-role-session\",\n sts_client_kwargs={\n \"region_name\": \"us-east-1\",\n \"config\": Config(\n retries={\n \"total_max_attempts\": 10,\n \"mode\": \"adaptive\"\n }\n )\n },\n assume_role_kwargs={\n \"DurationSeconds\": 900\n }\n)\n```\n\n## Development\n\nInstall the package in editable mode with dev dependencies.\n\n```text\n(venv) $ pip install -e .[dev,all]\n```\n\n[nox](https://nox.thea.codes/en/stable/) is used to manage various dev functions.\nStart with\n\n```text\n(venv) $ nox --help\n```\n\n[pyenv](https://github.com/pyenv/pyenv) is used to manage python versions. \nTo run the nox tests for applicable python version you will first need to install them. \nIn the root project dir run:\n\n```text\n(venv) $ pyenv install\n```\n\n# Changelog\n\nChangelog for `boto3-assume`.\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n<!--\n## [Unreleased] - YYYY-MM-DD\n\n### Added\n\n### Changed\n\n### Deprecated\n\n### Removed\n\n### Fixed\n\n### Security \n-->\n\n## [0.1.2] - 2024-05-18\n\n### Removed\n - `boto3` and `aioboto3` package extras. They didn't work and weren't documented correctly. \n\n### Fixed\n - `datetime.datetime.utcnow()` deprecation in tests for python 3.12\n\n\n## [0.1.1] - 2023-06-28\n\n### Fixed\n - Formatting for Changelog, README\n\n\n## [0.1.0] - 2023-06-28\n\nInitial Release.\n\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Easily create boto3/aioboto3 assume role sessions with automatic credential refreshing.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/btemplep/boto3-assume",
"Repository": "https://github.com/btemplep/boto3-assume"
},
"split_keywords": [
"aio",
" aioboto3",
" aiobotocore",
" assume",
" async",
" asyncio",
" aws",
" boto3",
" botocore",
" credentials",
" creds",
" iam",
" refresh",
" refreshable",
" role",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "70ee8bbe0c34732cffab6ef4a8faa849fc871628663fdfd0b0f88da5df1b2b60",
"md5": "eee04c666bf466fa5f7397c0dff5af29",
"sha256": "e62eb52df0eb81046565a17304a6f8d566ec03572199c9b83a4e78c1acafb307"
},
"downloads": -1,
"filename": "boto3_assume-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eee04c666bf466fa5f7397c0dff5af29",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10415,
"upload_time": "2024-05-19T00:56:41",
"upload_time_iso_8601": "2024-05-19T00:56:41.433727Z",
"url": "https://files.pythonhosted.org/packages/70/ee/8bbe0c34732cffab6ef4a8faa849fc871628663fdfd0b0f88da5df1b2b60/boto3_assume-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f6c9bb3790c1722e897a3e7683e72a01d7b3a38bfa3ea35a3b899a4c201949a4",
"md5": "8e7abae80ab072fb808a3fded760ed40",
"sha256": "314cdc6e4913fa80849870b72596a2b8dd3139d56590d8c20c7e2684a65e7456"
},
"downloads": -1,
"filename": "boto3_assume-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "8e7abae80ab072fb808a3fded760ed40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10558,
"upload_time": "2024-05-19T00:56:42",
"upload_time_iso_8601": "2024-05-19T00:56:42.975702Z",
"url": "https://files.pythonhosted.org/packages/f6/c9/bb3790c1722e897a3e7683e72a01d7b3a38bfa3ea35a3b899a4c201949a4/boto3_assume-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-19 00:56:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "btemplep",
"github_project": "boto3-assume",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "boto3-assume"
}
JSON
