{"id":26210512,"url":"https://github.com/civisanalytics/iam-role-injector","last_synced_at":"2025-07-30T21:33:23.625Z","repository":{"id":34106372,"uuid":"37934487","full_name":"civisanalytics/iam-role-injector","owner":"civisanalytics","description":"Assumes an IAM role via awscli STS call, injecting temporary credentials into shell environment","archived":false,"fork":false,"pushed_at":"2024-03-18T14:50:48.000Z","size":43,"stargazers_count":27,"open_issues_count":0,"forks_count":11,"subscribers_count":132,"default_branch":"master","last_synced_at":"2025-04-15T14:04:54.989Z","etag":null,"topics":["iam","shell","sts"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/civisanalytics.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-23T17:40:37.000Z","updated_at":"2025-02-26T20:39:19.000Z","dependencies_parsed_at":"2025-03-12T07:39:23.657Z","dependency_job_id":null,"html_url":"https://github.com/civisanalytics/iam-role-injector","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/civisanalytics/iam-role-injector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civisanalytics%2Fiam-role-injector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civisanalytics%2Fiam-role-injector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civisanalytics%2Fiam-role-injector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civisanalytics%2Fiam-role-injector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/civisanalytics","download_url":"https://codeload.github.com/civisanalytics/iam-role-injector/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civisanalytics%2Fiam-role-injector/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267945013,"owners_count":24170214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"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":["iam","shell","sts"],"created_at":"2025-03-12T07:29:17.725Z","updated_at":"2025-07-30T21:33:23.591Z","avatar_url":"https://github.com/civisanalytics.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iam-role-injector\n\nThe IAM Role Injector is a tool for easily assuming an IAM Role with\nMulti-Factor Authentication (MFA). It manipulates environment variables\nto allow codebases already using AWS credentials to use IAM roles with minimal to no\nrefactoring. In the same vein, the Role Injector can also be used to help users using the\ncommand line tools to assume a role.\n\n## Assumptions\n - AWS CLI configured correctly, storing 'aws_access_key_id' and\n   'aws_secret_access_key' in either environment variables -OR- in\n   ~/.aws/credentials\n - One of the following Scenarios apply:\n\n### Scenario One: Federated AWS Accounts\n - At least two AWS Accounts:\n   - AWS Account 1 must have a policy that includes sts:AssumeRole to AWS Account 2\n   - AWS Account 2 must have a Trust Relationship on a role that references AWS Account 1\n - AWS Account 1 may now assume the role in AWS Account 2 that has the Trust Relationship\n\n### Scenario Two: Single AWS Account\n - An IAM User Account with a policy that include sts:Assume on an IAM\n   Role.\n - The IAM Role has a trust relationship that allows entities in the\n   account to assume it\n - In this case, AWS Account 1 and AWS Account 2 are the same.\n\n## Installation\n\n1. [Install AWS CLI](http://docs.aws.amazon.com/cli/latest/userguide/installing.html)\n2. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) with required credentials, either as Environment\n   Variables or by running 'aws configure'\n3. Clone this repo\n\n## Increase AWS IAM Role max-session-duration\n1 hour is used by default (following the AWS assume-role default), if no timeout time is specified.\nTo update an AWS IAM role beyond 1 hour using the sts assume-role call, you must initially update the IAM role with a max-session-duration (in seconds).\ne.g. (for 12 hours):\n\n`aws iam update-role --role-name administrator --max-session-duration 43200`\n\n## Command Line Usage\n\n**IMPORTANT NOTE: The command below starts with \"source\"! If you run the script without sourcing it, the environment variables will go out of scope when the script ends and you'll have a bad time.**\n\n*source /path/to/sts_assume_role.sh -d [destination_account__number] -r [rolename]*\n\ne.g.\n`source /path/to/sts_assume_role.sh -d 1234567890 -r administrator`\n\ne.g.\n`source /path/to/sts_assume_role.sh --source 9876543210 --user iam-user --destination 1234567890 --role administrator --timeout 6h --mfa 552255`\n\n### Optional features:\n#### Help menu\n```\n/path/to/sts_assume_role.sh -h\n[Help Menu Options]\nSpecify at least a role (-r) and destination account (-d)\n    -d|--destination    to which AWS account you will assume-role\n    -h|--help           (this) help menu\n    -i|--info           output aws Info\n    -m|--mfa            multi-factor (2fa/mfa) authentication (default is NONE)\n    -r|--role           aws role you wish be become\n    -s|--source         source account id (not needed if you can 'aws iam list-account-aliases')\n    -t|--timeout        duration in which assume-role will be functional\n                        (values in (s)econds,(m)inutes,(h)ours - 60m up to 12h. Default is 3600s)\n    -u|--user           iam user name (not needed if you can 'aws sts get-caller-identity')\n    -x|--unset          unset assumed role vars\n```\n\n#### Show current iam user or role info\n`/path/to/sts_assume_role.sh -i`\n#### Revert to iam user from role\n`/path/to/sts_assume_role.sh -x`\n#### Specify expiration (aws sts now supports from 1 hour, up to 12 hours)\n`source /path/to/sts_assume_role.sh -d [destination_account__number] -r [rolename] -t 4h`\n*works with seconds, minutes, or hours. e.g. `-t 2h` `-t 120m` `-t 7200s` `-t 7200`*\n### Specify nothing, and you will be prompted for necessary information\n```\nsource /path/to/sts_assume_role.sh\n[No values set, please enter at least the destination account number and role name to assume a role]\nSource Account (Default is NONE): 9876543210\nDestination Account: 1234567890\nIAM User Name (Default is NONE): iam-user\nRole: administrator\nTimeout (Default is 1h):\nMultifactor Authentication? (default is NONE):\n```\n\n### Variables exported\n```\nAWS_ACCOUNT_NAME\nAWS_ACCESS_KEY_ID\nAWS_ENV_VARS\nAWS_SECRET_ACCESS_KEY\nAWS_SESSION_TOKEN\nAWS_STS_EXPIRATION\nAWS_STS_TIMEOUT\nAWS_USER\nOG_AWS_ACCESS_KEY_ID\nOG_AWS_SECRET_ACCESS_KEY\n```\n\n### Expiration/Timeout use case\n`AWS_STS_EXPIRATION` and `AWS_STS_TIMEOUT` are helpful to create a basic functions to determine how much time until the assume-role has\nexpired.\n\n```\nfunction timeToSTSExpiration(){\n  echo $(( $(( ${AWS_STS_TIMEOUT} - $(date -u +%s) )) / 60 ))\n}\n```\n\nIt can even be added to your prompt. e.g.\n```\nfunction checkSTS() {\nif [[ -n $AWS_STS_EXPIRATION \u0026\u0026 $AWS_STS_TIMEOUT -ge $(date +%s) ]]; then\n  AWS_STS_MINUTES_REMAINING=$(( $(( AWS_STS_TIMEOUT - $(date -u +%s) )) / 60 ))\n  echo \"$AWS_ACCOUNT_NAME|$AWS_STS_MINUTES_REMAINING\"\nelif [[ $AWS_STS_TIMEOUT -le $(date +%s) ]]; then\n  unset AWS_STS_EXPIRATION\nfi\nSTS_PROMPT_=\"$STS_COLOR\"'$(checkSTS)'\nPROMPT=\"$STS_PROMPT \u003e\"\n```\n\n# Legacy script\n```\nsource ~/assume_role.sh {sourceAccountNumber} {username} {destinationAccountNumber} {rolename}\n```\n\n - `sourceAccountNumber`: AWS Account Number of AWS Account 1\n - `username`: AWS Account 1 username\n - `destinationAccountNumber`: AWS Account Number of AWS Account 2\n - `rolename`: the name of the role to assume in AWS Account 2 that has the Trust Relationship to AWS Account 1\n\nCalling the script with 'source' is required for the\nenvironment variables to persist past the runtime of the script.\n\nThe script will also protect your original credentials if you chose to\nstore *them* as environment variables.\n\n## Bugs\n\nPlease report any bugs to:\nhttps://github.com/civisanalytics/iam-role-injector/issues\n\n## Contributing\n\nOpen an issue or a pull request if you see how we can improve the\nscript!\n\n\n## License\n\n iam-role-injector is released under the [BSD 3-Clause License](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcivisanalytics%2Fiam-role-injector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcivisanalytics%2Fiam-role-injector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcivisanalytics%2Fiam-role-injector/lists"}