{"id":24517773,"url":"https://github.com/fstab50/stslib","last_synced_at":"2026-05-11T02:50:19.012Z","repository":{"id":50211340,"uuid":"109512701","full_name":"fstab50/stslib","owner":"fstab50","description":"Library for Generating Temporary Credentials using Amazon Web Services' Secure Token Service (STS)","archived":false,"fork":false,"pushed_at":"2022-12-08T00:40:41.000Z","size":293,"stargazers_count":1,"open_issues_count":52,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-29T18:13:47.637Z","etag":null,"topics":["amazon-web-services","aws","iam","iam-credentials","secure-token-service","sts-credentials","temporary-credentials"],"latest_commit_sha":null,"homepage":"http://stsaval.readthedocs.io/en/latest","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fstab50.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-04T16:51:03.000Z","updated_at":"2020-03-01T21:00:29.000Z","dependencies_parsed_at":"2023-01-25T01:31:07.885Z","dependency_job_id":null,"html_url":"https://github.com/fstab50/stslib","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fstab50/stslib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fstab50%2Fstslib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fstab50%2Fstslib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fstab50%2Fstslib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fstab50%2Fstslib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fstab50","download_url":"https://codeload.github.com/fstab50/stslib/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fstab50%2Fstslib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32879551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-web-services","aws","iam","iam-credentials","secure-token-service","sts-credentials","temporary-credentials"],"created_at":"2025-01-22T01:35:12.328Z","updated_at":"2026-05-11T02:50:18.997Z","avatar_url":"https://github.com/fstab50.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"* * *\n# stslib\n\n### Generate STS Credentials for [Amazon Web Services](https://aws.amazon.com)\n\n[![GitHub release](https://img.shields.io/badge/release-v0.3.8-blue.svg)](https://github.com/fstab50/stslib/tree/master)\n[![Jenkins](https://img.shields.io/jenkins/s/https/jenkins.qa.ubuntu.com/view/Precise/view/All%20Precise/job/precise-desktop-amd64_default.svg)](https://readthedocs.org/projects/stslib/builds/)\n[![Read the Docs](https://img.shields.io/readthedocs/pip.svg)](http://stslib.readthedocs.io)\n[![PyPI](https://img.shields.io/badge/python-3.5%2C%203.6-blue.svg)](https://docs.python.org/3/whatsnew/3.6.html)\n[![Deps](https://img.shields.io/badge/dependencies-boto3%2C%20awscli%2C%20pytz-yellow.svg)](https://pypi.python.org/pypi/boto3/1.4.7)\n[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0.html)\n[![Platorm](https://img.shields.io/badge/platform-linux--64%20%7C%20osx--64-lightgrey.svg)](https://en.wikipedia.org/wiki/Linux)\n\n* * *\n\n* * *\n\n## Purpose ##\n\n**stslib** is a python3 library that requests and manages temporary credentials from [Amazon's Security Token Service (STS)](http://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html)  \non your behalf. **stslib** generates temporary credentials against roles that reside in any number of AWS  accounts.  \n\nThe **stslib** library is commonly used in python applications that generate temporary access credentials for  \nautomation tools which need to _bypass multi-factor authentication enabled on Amazon APIs_.  Temporary credentials  \nof this type are are required authenticate to Amazon Web Services (AWS) when automation tooling is used to deploy  \nto tens or even hundreds of AWS accounts simultaneously.\n\n**stslib** is appropriate for authentication to AWS Services both from within AWS as well by automation tooling  \nruns in an environment external to AWS such as an on-prem datacenter or local machine.\nlocal machine.\n\n**stslib** manages temporary credentials generates credentials in memory for applications that need access to  \niam roles at AWS.  If temporary credentials are needed for extended periods (\u003e 1 hour), **stslib** will automatically  \nrenew sts credentials before expiration.\n\n\n* * *\n\n## Documentation ##\n\n**Online Documentation**:\n\n* Complete html documentation available at [http://stslib.readthedocs.io](http://stslib.readthedocs.io).\n\n**Download Documentation**:\n\n* [pdf format](https://readthedocs.org/projects/stslib/downloads/pdf/stable/)\n* [Amazon Kindle](https://readthedocs.org/projects/stslib/downloads/epub/stable/) (epub) format\n\n* * *\n\n## Getting Started\n\nBefore starting, read the following to understand **stslib** key concepts and use cases:\n\n* [Frequently Asked Questions (FAQ)](./FAQ.md)\n* [Credential Format Overview](http://stslib.readthedocs.io/en/latest/primer/credential-format-overview.html) -- A primer on the dual credential formats supported by **stslib**\n* [Code Examples](http://stslib.readthedocs.io/en/latest/code_examples/toctree_code_examples.html)\n\n\n**stslib** is licensed under [General Public License v3](http://stslib.readthedocs.io/en/latest/license.html)\n\n\n* * *\n\n## Dependencies ##\n\n- Python3 via one of the following:\n    - Python 3.5.X+\n    - Python 3.6.X+\n- Installation of Amazon CLI tools (awscli, see Installation section)\n- Linux Operating System, one of the following:\n    - Redhat Enterprise Linux v7.X (preferred)\n    - Ubuntu 14.04, (Ubuntu 16.04 preferred)\n    - Amazon Linux (2017.03+ )\n\n* * *\n\n## Installation - Redhat / Ubuntu ##\n\n* Install [awscli](https://github.com/aws/aws-cli/)\n\n    Detailed instructions can be found in the README located at:\n    https://github.com/aws/aws-cli/\n\n    The easiest method, provided your platform supports it, is via [pip](http://www.pip-installer.org/en/latest).\n\n```bash\n    $ sudo pip install awscli\n```\n\n* If you have the aws-cli installed and want to upgrade to the latest version you can run:\n\n```bash\n    $ sudo pip install --upgrade awscli\n```\n\n* Installation via pip\n\n```bash\n    $ sudo -H pip3 install stslib\n```\n\n* Setup and Configuration\n\n```bash\n    $ cd /home/user/\u003cstslib directory\u003e/\n    $ python3 ...TBD\n```\n\n* * *\n# Use Cases \u0026 Examples #\n* * *\n\n### Generate Session Token (default IAM User)\n\n* `Default` profile in local awscli config. Default user has permissions to assume roles for which **stslib**  \nwill generate credentials\n* Token with default lifetime (60 minutes)\n* Cli _not_ protected with MFA (Multi-Factor Authentication, 6 digit code)\n\n```python\n\n    from stslib import StsCore\n\n    \u003e\u003e\u003e sts_object = StsCore()\n    \u003e\u003e\u003e token = sts_object.generate_session_token()\n    \u003e\u003e\u003e print(token)\n    \u003cstslib.vault.STSToken at 0x7f05365e3ef0\u003e\n\n    # token attributes\n\n    \u003e\u003e\u003e print(token.start)\n    datetime.datetime(2017, 8, 25, 20, 4, 37, tzinfo=tzutc()\n\n    \u003e\u003e\u003e print(token.end)\n    datetime.datetime(2017, 8, 25, 21, 4, 36, tzinfo=tzutc())\n\n    \u003e\u003e\u003e print(token.access_key)\n    'ASIAI6QV2U3JJAYRHCJQ'\n\n    \u003e\u003e\u003e print(token.secret_key)\n    'MdjPAkXTHl12k64LSjmgTWMsmnHk4cJfeMHdXMLA'\n\n    \u003e\u003e\u003e print(token.session)\n    'FQoDYXdzEDMaDHAaP2wi/+77fNJJryKvAa20AqGxoQlcRtf8RFLa5Mps9zK9V5SM3Q7+M3h9iNbcxfaZsUnTzFvFwjVZjYKk...zQU='\n\n    \u003e\u003e\u003e print(token.boto)    # native boto generated format\n\n{\n    'AccessKeyId': 'ASIAI6QV2U3JJAYRHCJQ',\n    'StartTime': datetime.datetime(2017, 8, 25, 20, 4, 37, tzinfo=tzutc()),\n    'Expiration': datetime.datetime(2017, 8, 25, 21, 4, 36, tzinfo=tzutc()),\n    'SecretAccessKey': 'MdjPAkXTHl12k64LSjmgTWMsmnHk4cJfeMHdXMLA',\n    'SessionToken': 'FQoDYXdzEDMaDHAaP2wi/+77fNJJryKvAa20AqGxoQlcRtf8RFLa5Mps9zK9V5SM3Q7+M3h9iNbcxfa...zQU='\n}\n\n```\n\n### Generate Session Token (named IAM User)\n\n* Named IAM user profile in local awscli config. User has permissions to assume roles for which **stslib**  \nwill generate credentials\n* MFA protected cli access configuration\n* STS Token with default lifetime (60 minutes)\n\n```python\n\n    from stslib import StsCore\n\n    \u003e\u003e\u003e sts_object = StsCore(profile_name='BobSmith')\n    \u003e\u003e\u003e code = '123456'\n    \u003e\u003e\u003e token = sts_object.generate_session_token(mfa_code=code)\n\n    \u003e\u003e\u003e print(token.boto)\n\n{\n    'AccessKeyId': 'ASIAI6QV2U3JJAYRHCJQ',\n    'StartTime': datetime.datetime(2017, 8, 25, 20, 4, 37, tzinfo=tzutc()),\n    'Expiration': datetime.datetime(2017, 8, 25, 21, 4, 36, tzinfo=tzutc()),\n    'SecretAccessKey': 'MdjPAkXTHl12k64LSjmgTWMsmnHk4cJfeMHdXMLA',\n    'SessionToken': 'FQoDYXdzEDMaDHAaP2wi/+77fNJJryKvAdVZjYKk...zQU='\n}\n\n```\n\n* * *\n\n### Generate Credentials (1 hour lifetime)\n\n* generate STS temporary credentials, default lifetime (60 minutes)\n* Credential format set to 'vault' (default stslib format)\n* **stslib** supports 2 credential formats.  See the [Credential Format Overview](./docs/markdown/credential-format-overview.md).  \n\n```python\n\n    \u003e\u003e\u003e sts_object = StsCore(profile_name='BobSmith')\n    \u003e\u003e\u003e token = sts_object.generate_session_token()\n    \u003e\u003e\u003e profile_list = [\n            'DynamoDBRole-dev', 'CodeDeployRole-qa', 'S3ReadOnlyRole-prod'\n        ]\n\n            # where profile_list = list of profile names from local awscli config\n\n    \u003e\u003e\u003e sts_object.generate_credentials(profile_list)\n\n    \u003e\u003e\u003e print(credentials)     \n\n{\n    'sts-DynamoDBRole-dev': \u003cstslib.vault.STSingleSet at 0x7fee0ae05c88\u003e,\n    'sts-CodeDeployRole-qa': \u003cstslib.vault.STSingleSet at 0x7fee0ae05f60\u003e,\n    'sts-S3ReadOnlyRole-prod': \u003cstslib.vault.STSingleSet at 0x7fee0ae05fd0\u003e\n}\n\n```\n\n* * *\n\n### Generate Extended Use Credentials (Multi-hour, Auto-refresh)\n\n* Named IAM user profile in local awscli config. User has permissions to assume roles for which stslib  \nwill generate credentials\n* MFA protected cli configuration\n* Credential format set to 'boto' (native Amazon STS format)\n* Credentials auto-refreshed for total 5 hour valid lifetime without MFA auth\n\n```python\n\n    from stslib import StsCore\n\n    \u003e\u003e\u003e sts_object = StsCore(profile_name='BobSmith', format='boto')            # boto format credentials\n    \u003e\u003e\u003e code = '123456'\n    \u003e\u003e\u003e token = sts_object.generate_session_token(lifetime=5, mfa_code=code)    # 5 hour lifetime triggers auto-refresh\n    \u003e\u003e\u003e profile_list = [\n            'DynamoDBRole-dev', 'CodeDeployRole-qa', 'S3ReadOnlyRole-prod'\n        ]\n\n            # where profile_list = list of profile names from local awscli config\n\n    \u003e\u003e\u003e sts_object.generate_credentials(profile_list)\n    \u003e\u003e\u003e credentials = sts_object.current_credentials\n\n```\n\n#### Auto-Refresh of Credentials\n\n* **stslib** will automatically generate new temporary credentials once per hour, prior to expiration (process below)\n\n\n```python\n\n    \u003e\u003e\u003e print(credentials())        \n\n{\n  'sts-DynamoDBRole-dev': {        \n      'StartTime': datetime.datetime(2017, 10, 1, 14, 17, 45, 652218, tzinfo=\u003cUTC\u003e)},\n      'Expiration': datetime.datetime(2017, 10, 1, 15, 17, 45, tzinfo=tzutc()),\n      'AccessKeyId': 'ASIAJRW7F2BAVN4J34LQ',\n      'SecretAccessKey': 'P8EjwTUKL4hil4Y7Ouo9OkFzQ1IxGikbhIjMP5uN',\n      'SessionToken': 'FQoDYXdzEDMaDCpxZzDdwWGok/ylQiLcAdlrHCkxP+kvQOes3mnQ0r5GXt...'\n  },\n  'sts-CodeDeployRole-qa': {\n      'StartTime': datetime.datetime(2017, 10, 1, 14, 17, 45, 652218, tzinfo=\u003cUTC\u003e)},\n      'Expiration': datetime.datetime(2017, 10, 1, 15, 17, 45, tzinfo=tzutc()),\n      'AccessKeyId': 'ASIAIOOOKUYFICAPC6TQ',\n      'SecretAccessKey': '3Q+N4UMpbmW7OrvY2mfgbjXxr/qt1L4XqmO+Njpq',\n      'SessionToken': 'FQoDYXdzEDMaDL/sJkeAF28UsxE/iyLUAbvBrCUoAkP/eqeS...'\n  },\n  'sts-S3ReadOnlyRole-prod': {        \n      'StartTime': datetime.datetime(2017, 10, 1, 14, 17, 45, 652218, tzinfo=\u003cUTC\u003e)}}\n      'Expiration': datetime.datetime(2017, 10, 1, 15, 17, 46, tzinfo=tzutc()),\n      'AccessKeyId': 'ASIAJPRTS4IXPYGPLKZA',\n      'SecretAccessKey': 'EMAfJUz5zMNOyjKl7U2IWpJ0GCtWCos0squOE0wz',\n      'SessionToken': 'FQoDYXdzEDMaDO0ekTXJi4+IRWV1ESLXAe1ZfOpmGcS9hbIr...'\n  }\n}\n\n# stdout log stream\n/stslib/core.py - 0.2.0 - [INFO]: _validate: Valid account profile names: ['DynamoDBRole-dev', 'CodeDeployRole-qa', 'S3ReadOnlyRole-prod']\n/stslib/async.py - 0.2.0 - [INFO]: executing event: \u003cbound method StsCore.generate_credentials of \u003cstslib.core.StsCore object at 0x7f91c9df02e8\u003e\u003e\n/stslib/async.py - 0.2.0 - [INFO]: thread identifier: Thread-150\n/stslib/async.py - 0.2.0 - [INFO]: thread Alive status is: True\n/stslib/async.py - 0.2.0 - [INFO]: completed 1 out of 5 total executions\n/stslib/async.py - 0.2.0 - [INFO]: remaining in cycle: 4 hours, 59 minutes\n\n\n  \u003e\u003e\u003e print(credentials())\n\n{\n  'sts-DynamoDBRole-dev': {        \n      'StartTime': datetime.datetime(2017, 10, 1, 15, 17, 45, 652218, tzinfo=\u003cUTC\u003e)},\n      'Expiration': datetime.datetime(2017, 10, 1, 16, 17, 45, tzinfo=tzutc()),\n      'AccessKeyId': 'ASIAJRW7F2BAVN4J34LQ',\n      'SecretAccessKey': 'P8EjwTUKL4hil4Y7Ouo9OkFzQ1IxGikbhIjMP5uN',\n      'SessionToken': 'FQoDYXdzEDMaDCpxZzDdwWGok/ylQiLcAdlrHCkxP+kvQOes3mnQ0r5GXt...'\n  },\n  'sts-CodeDeployRole-qa': {\n      'StartTime': datetime.datetime(2017, 10, 1, 15, 17, 45, 652218, tzinfo=\u003cUTC\u003e)},\n      'Expiration': datetime.datetime(2017, 10, 1, 16, 17, 45, tzinfo=tzutc()),\n      'AccessKeyId': 'ASIAIOOOKUYFICAPC6TQ',\n      'SecretAccessKey': '3Q+N4UMpbmW7OrvY2mfgbjXxr/qt1L4XqmO+Njpq',\n      'SessionToken': 'FQoDYXdzEDMaDL/sJkeAF28UsxE/iyLUAbvBrCUoAkP/eqeS...'\n  },\n  'sts-S3ReadOnlyRole-prod': {        \n      'StartTime': datetime.datetime(2017, 10, 1, 15, 17, 45, 652218, tzinfo=\u003cUTC\u003e)}}\n      'Expiration': datetime.datetime(2017, 10, 1, 16, 17, 46, tzinfo=tzutc()),\n      'AccessKeyId': 'ASIAJPRTS4IXPYGPLKZA',\n      'SecretAccessKey': 'EMAfJUz5zMNOyjKl7U2IWpJ0GCtWCos0squOE0wz',\n      'SessionToken': 'FQoDYXdzEDMaDO0ekTXJi4+IRWV1ESLXAe1ZfOpmGcS9hbIr...'\n  }\n}\n\n# stdout log stream\n/stslib/core.py - 0.2.0 - [INFO]: _validate: Valid account profile names: ['DynamoDBRole-dev', 'CodeDeployRole-qa', 'S3ReadOnlyRole-prod']\n/stslib/async.py - 0.2.0 - [INFO]: thread identifier: Thread-150\n/stslib/async.py - 0.2.0 - [INFO]: thread Alive status is: True\n/stslib/async.py - 0.2.0 - [INFO]: completed 2 out of 5 total executions\n/stslib/async.py - 0.2.0 - [INFO]: remaining in cycle: 3 hours, 59 minutes\n\n```\n\n#### Auto-Refresh Credentials -- Additional Info\n\n* Refresh of credentials is non-blocking (via threading)\n* Thread management is via event states; threads are terminated as soon as their associated  \nsession token expires or they receive a halt event.\n* No hanging threads. Any live threads when new credentials generated are safely terminated  \nbefore generating a new set.\n\n* * *\n\n### Non-default IAM Role credentials filename or location\n\n**Use-Case**: When you wish to use role credentials file not currently part of the awscli,  \nyou can provide a custom location to stslib as a parameter\n\n* Initialization\n\n```python\n\n    import stslib\n\n    \u003e\u003e\u003e sts_object = stslib.StsCore()\n    \u003e\u003e\u003e credentials_file = '~/myAccount/role_credentials'   # awscli credentials file, located in ~/.aws\n\n    \u003e\u003e\u003e sts_object.refactor(credentials_file)\n    \u003e\u003e\u003e sts_object.profiles\n```\n\n* Output\n\n```json\n\n{\n    \"acme-db-dev\": {\n        \"role_arn\": \"arn:aws:iam::236600111358:role/AcmeDEV\",\n        \"mfa_serial\": \"arn:aws:iam::3788881165911:mfa/BillCaster\",\n        \"source_profile\": \"william-caster\"\n    },\n    \"acme-apps-dev\": {\n        \"role_arn\": \"arn:aws:iam::123660943358:role/AcmeDEV\",\n        \"mfa_serial\": \"arn:aws:iam::3788881165911:mfa/BillCaster\",\n        \"source_profile\": \"william-caster\"\n    },\n    \"acme-apps-qa\": {\n        \"role_arn\": \"arn:aws:iam::430864833800:role/AcmeAdmin\",\n        \"mfa_serial\": \"arn:aws:iam::3788881165911:mfa/BillCaster\",\n        \"source_profile\": \"william-caster\"\n    },\n    \"acme-prod08\": {\n        \"role_arn\": \"arn:aws:iam::798623437252:role/EC2RORole\",\n        \"mfa_serial\": \"arn:aws:iam::3788881165911:mfa/BillCaster\",\n        \"source_profile\": \"william-caster\"\n    },\n    \"acme-prod09\": {\n        \"role_arn\": \"arn:aws:iam::123660943358:role/S3Role\",\n        \"mfa_serial\": \"arn:aws:iam::3788881165911:mfa/BillCaster\",\n        \"source_profile\": \"william-caster\"\n    }\n}\n\n```\n\n* * *\n\n## FAQ ##\n\nsee [Frequently Asked Questions](./FAQ.md)\n\n* * *\n\n## Enhancement Roadmap ##\n\nA summary roadmap can be found [here](http://stslib.readthedocs.io/en/latest/roadmap.html).\n\nFor a complete list of enhancements logged against the stslib project, see the [list of stslib issues](https://github.com/fstab50/stslib/issues?q=is%3Aopen).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffstab50%2Fstslib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffstab50%2Fstslib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffstab50%2Fstslib/lists"}