{"id":13796104,"url":"https://github.com/coinbase/assume-role","last_synced_at":"2025-05-13T00:30:42.256Z","repository":{"id":66163489,"uuid":"106505574","full_name":"coinbase/assume-role","owner":"coinbase","description":"DEPRECATED — assume-role: a CLI tool making it easy to assume IAM roles through an AWS Bastion account","archived":true,"fork":false,"pushed_at":"2020-01-10T00:06:44.000Z","size":1112,"stargazers_count":423,"open_issues_count":0,"forks_count":74,"subscribers_count":32,"default_branch":"master","last_synced_at":"2024-04-14T16:48:44.284Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coinbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-10-11T04:27:31.000Z","updated_at":"2024-03-14T16:29:32.000Z","dependencies_parsed_at":"2023-03-10T23:41:57.847Z","dependency_job_id":null,"html_url":"https://github.com/coinbase/assume-role","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fassume-role","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fassume-role/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fassume-role/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fassume-role/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coinbase","download_url":"https://codeload.github.com/coinbase/assume-role/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225159846,"owners_count":17430191,"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","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":[],"created_at":"2024-08-03T23:01:06.194Z","updated_at":"2024-11-18T10:31:04.537Z","avatar_url":"https://github.com/coinbase.png","language":"Shell","funding_links":[],"categories":["Shell","Amazon Web Services"],"sub_categories":[],"readme":"# DEPRECATED - assume-role\nThis repository is no longer maintained.\n\n\u003cimg src=\"./assets/assume-role.png\" align=\"right\" alt=\"assume-role logo\" /\u003e\n\nAssume IAM roles through an **AWS Bastion** account with **MFA** or **SAML Provider**  via the command line.\n\n**AWS Bastion** accounts store only IAM users providing a central, isolated account to manage their credentials and access. Trusting AWS accounts create IAM roles that the Bastion users can assume, to allow a single user access to multiple accounts resources. Under this setup, `assume-role` makes it easier to follow the standard security practices of MFA and short lived credentials.\n\n**SAML Providers** allow you to use federated login to assume-role-with-saml. SAML Assertions should be\n[formatted as following](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html)\naccording to AWS.\n\n## Installation\n\n`assume-role` requires [`jq`](https://stedolan.github.io/jq/) and [`aws`](https://aws.amazon.com/cli/) CLI tools to be installed.\n\n### via Homebrew (macOS)\n\n```bash\nbrew tap coinbase/assume-role\nbrew install assume-role\n```\n\nYou can then upgrade at any time by running:\n\n```bash\nbrew upgrade assume-role\n```\n\n### via Bash (Linux/macOS)\n\nYou can install/upgrade assume-role with this command:\n\n```bash\ncurl https://raw.githubusercontent.com/coinbase/assume-role/master/install-assume-role -O\ncat install-assume-role # inspect the script for security\nbash ./install-assume-role # install assume-role\n```\n\nIt will ask for your sudo password if necessary.\n\n## Getting Started\n\nIf you are using a bastion setup (the default), make sure that credentials for your AWS bastion account are stored in `~/.aws/credentials`.\n\nOut of the box you can call `assume-role` like:\n\n```bash\neval $(assume-role account-id role mfa-token)\n```\n\nIf your shell supports bash functions (e.g. zsh) then you can add `source $(which assume-role)` to your `rc` file (e.g. `~/.zshrc`), then you can call `assume-role` like:\n\n```bash\nassume-role [account-id] [role] [mfa-token]\n```\n\n`assume-role` this method can be used with arguments or interactively like:\n\n\u003cimg src=\"./assets/assume-role.gif\" alt=\"assume-role usage\" /\u003e\n\n### SAML authentication\n\nIf you would like to authenticate with your SAML provider using username and password instead, add this to your `.bash_profile` or `.bashrc`:\n```\nexport AWS_ASSUME_ROLE_AUTH_SCHEME=saml # defaults to bastion\nexport SAML_IDP_ASSERTION_URL=\"your saml idp assertion url\"\nexport SAML_IDP_NAME=\"Name of your IdP registerd with AWS\"\n# This is an example body template.\nexport SAML_IDP_REQUEST_BODY_TEMPLATE='{\"service\": \"aws\", \"email\": \"$saml_user\", \"password\": \"$saml_password\"}'\n```\n\nThe URL should serve a POST API that returns a SAML Assertion under the `saml_response` JSON key.\n\nYou can specify your JSON body via an envar that uses the `saml_user` and `saml_password` envars. You can specify any body template you want.\n\nYour service should be hosted over SSL since credentials might be sent in the response, depending on your JSON body implementation.\nYou could hash the password client-side if you wish to do so in the template envar\n\nThe script will warn you if you are not serving over SSL.\n\nOnce you assume-role, you will be prompted for your SAML credentials (username and password).\n\nIf you would like to store your credentials on the filesystem for ease of use, you can create a `~/.saml/credentials` file.\n\nAn example of what this looks like is (example syntax; These are *not* real):\n```\nusername = lukeskywalker\npassword = hunter2\n```\n\n### Account Aliasing\n\nYou can define aliases to account ids in `~/.aws/accounts` which assume-role can use, e.g.\n\n```json\n{\n  \"default\": \"123456789012\",\n  \"staging\": \"123456789012\",\n  \"production\": \"123456789012\"\n}\n```\n\nWith this file, to assume the `read` role in the `production` account:\n\n```bash\nassume-role production read\n# OR\nassume-role 123456789012 read\n```\n\nAlso, by setting `$AWS_PROFILE_ASSUME_ROLE`, you can define a default profile for `assume-role` if you want to separate concerns between\ndefault accounts for `assume-role` and vanilla `awscli` or simply to have better names than `default`:\n\n```bash\n$ export AWS_PROFILE_ASSUME_ROLE=\"bastion\"\n$ assume-role production read\n```\n\nMoreover, if you are in the need of [longer client-side assume-role sessions](https://aws.amazon.com/about-aws/whats-new/2018/03/longer-role-sessions/) and don't want to [enter your MFA authentication every hour (default)](https://github.com/coinbase/assume-role/issues/19) this one is for you:\n\n```bash\n$ export AWS_ROLE_SESSION_TIMEOUT=43200\n```\n\nHowever, be aware that for [chained roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-role-chaining) there's currently a forced **1 hour limit** from AWS. You'll get the following error if you exceed that specific limit:\n\n\u003e DurationSeconds exceeds the 1 hour session limit for roles assumed by role chaining.\n\nYou can also override the AWS IAM username which is usually fetched from the AWS IAM get-user api. This might not be allowed in some environments though:\n```bash\n$ export AWS_USERNAME=my_username\n```\n\n## AWS Bastion Account Setup\n\nHere is a simple example of how to set up a **Bastion** AWS account with an id `0987654321098` and a **Production** account with the id `123456789012`.\n\nIn the **Production** account create a role called `read`, with the trust relationship:\n\n```json\n{\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Principal\": {\n        \"AWS\": \"arn:aws:iam::0987654321098:root\"\n      },\n      \"Action\": \"sts:AssumeRole\",\n      \"Condition\": {\n        \"Bool\": {\n          \"aws:SecureTransport\": \"true\",\n          \"aws:MultiFactorAuthPresent\": \"true\"\n        },\n        \"NumericLessThan\": {\n          \"aws:MultiFactorAuthAge\": \"54000\"\n        }\n      }\n    }\n  ]\n}\n```\n\nThe conditions `aws:MultiFactorAuthPresent` and `aws:MultiFactorAuthAge` forces the use of temporary credentials secured with MFA.\n\nIn the **Bastion** account, create a group called `assume-read` with the policy:\n\n```json\n{\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [ \"sts:AssumeRole\" ],\n      \"Resource\": [ \"arn:aws:iam::123456789012:role/read\" ],\n      \"Condition\": {\n        \"Bool\": {\n          \"aws:MultiFactorAuthPresent\": \"true\",\n          \"aws:SecureTransport\": \"true\"\n        },\n        \"NumericLessThan\": {\n          \"aws:MultiFactorAuthAge\": \"54000\"\n        }\n      }\n    }\n  ]\n}\n```\n\nAttach this group to **Bastion** users that should be able use `read`'s policies in the **Production** account.\n\nYou can assume the `read` role in **Production** by running:\n\n```\nassume-role 123456789012 read\n```\n\nThen entering a MFA token on request.\n\n## SAML Provider setup\n\nThe SAML Provider will need to be registered in the same AWS account that you are doing assume-role-with-saml into. If you are dealing with many accounts,\nthe suggested way to handle this is to have one deployment of your SAML Provider that returns assertions for several accounts/roles using the registered\nSAML Provider ARN and the role ARN.\n\nHere is a simple example of how to set up a **SAML Provider** in a **Production** account with the id `123456789012`.\n\nIn the **Production** account create a saml provider called `saml-idp`, and a role called `read` with the trust relationship:\n\n```json\n{\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Principal\": {\n        \"Federated\": \"arn:aws:iam::123456789012:saml-provider/saml-idp\"\n      },\n      \"Action\": \"sts:AssumeRoleWithSAML\",\n      \"Condition\": {\n        \"Bool\": {\n          \"aws:SecureTransport\": \"true\",\n        },\n        \"StringEquals\": {\n          \"SAML:aud\": \"https://signin.aws.amazon.com/saml\"\n        }\n      }\n    }\n  ]\n}\n```\n\nAnd configure your SAML Provider to return signed assertions for the `read` role in the **Production** acount.\n\n## Prompt\n\nIf you are using `zsh` you can get a sweet prompt by adding to your `.zshrc` file:\n\n```bash\n# AWS ACCOUNT NAME\nfunction aws_account_info {\n  [ \"$AWS_ACCOUNT_NAME\" ] \u0026\u0026 [ \"$AWS_ACCOUNT_ROLE\" ] \u0026\u0026 echo \"%F{blue}aws:(%f%F{red}$AWS_ACCOUNT_NAME:$AWS_ACCOUNT_ROLE%f%F{blue})%F$reset_color\"\n}\n\n# )ofni_tnuocca_swa($ is $(aws_account_info) backwards\nPROMPT=`echo $PROMPT | rev | sed 's/ / )ofni_tnuocca_swa($ /'| rev`\n```\n\nFor `bash` you could put the following in your `.bash_profile` file:\n\n```bash\nfunction aws_account_info {\n  [ \"$AWS_ACCOUNT_NAME\" ] \u0026\u0026 [ \"$AWS_ACCOUNT_ROLE\" ] \u0026\u0026 echo -n \"aws:($AWS_ACCOUNT_NAME:$AWS_ACCOUNT_ROLE) \"\n}\n\nPROMPT_COMMAND='aws_account_info'\n```\n\n## Testing\n\nassume-role is tested with [BATS](https://github.com/sstephenson/bats) (Bash Automated Testing System). To run the tests first you will need `bats`, `jq` and `shellcheck` installed. On macOS this can be accomplished with `brew`:\n\n```bash\nbrew install bats\nbrew install jq\nbrew install shellcheck\n```\n\nThen run `bats test/assume-role.bats`;\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoinbase%2Fassume-role","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoinbase%2Fassume-role","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoinbase%2Fassume-role/lists"}