{"id":13707064,"url":"https://github.com/trussworks/setup-new-aws-user","last_synced_at":"2025-04-23T15:49:39.089Z","repository":{"id":37956117,"uuid":"220316655","full_name":"trussworks/setup-new-aws-user","owner":"trussworks","description":"Creates an MFA token and new access keys for an AWS user.","archived":false,"fork":false,"pushed_at":"2025-04-23T05:17:39.000Z","size":1019,"stargazers_count":11,"open_issues_count":2,"forks_count":4,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-23T06:24:56.275Z","etag":null,"topics":["access-keys","aws","iam","mfa"],"latest_commit_sha":null,"homepage":"https://github.com/trussworks/setup-new-aws-user","language":"Go","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/trussworks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-11-07T19:47:12.000Z","updated_at":"2025-04-23T05:17:42.000Z","dependencies_parsed_at":"2022-09-26T18:20:45.498Z","dependency_job_id":"2abac8ad-3f69-4138-9bb7-890c6c416c13","html_url":"https://github.com/trussworks/setup-new-aws-user","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trussworks%2Fsetup-new-aws-user","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trussworks%2Fsetup-new-aws-user/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trussworks%2Fsetup-new-aws-user/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trussworks%2Fsetup-new-aws-user/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trussworks","download_url":"https://codeload.github.com/trussworks/setup-new-aws-user/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250465531,"owners_count":21435204,"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":["access-keys","aws","iam","mfa"],"created_at":"2024-08-02T22:01:17.292Z","updated_at":"2025-04-23T15:49:39.067Z","avatar_url":"https://github.com/trussworks.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# setup-new-aws-user\n\nThis tool is used to grant programmatic access to AWS account(s) using\n[aws-vault](https://github.com/99designs/aws-vault). It works by taking a\ntemporary set of AWS access keys for a new IAM user. It then generates a\nvirtual MFA device and permanent set of access keys. Finally, it removes\nthe temporary access keys.\n\n## Installation\n\nFor Mac OS Homebrew:\n\n```shell\nbrew tap trussworks/tap\nbrew install setup-new-aws-user\n```\n\n### Dependencies\n\nThis tool requires aws-vault be installed. You can install via homebrew:\n\n```shell\nbrew install aws-vault\n```\n\n## Usage\n\nThis tool has several subcommands. Read each section to learn more.\n\n### setup-new-aws-user setup\n\nBefore running this tool, you will need to following pieces of information\n\n- IAM user name - This is your IAM username. Use the flag `--iam-user` with this value.\n- IAM role name - This is the IAM Role with permissions allowing access to AWS APIs\n  and services. This is usually something like `admin` or `engineer`. Use the flag\n  `--iam-role` with this value.\n- AWS Region - This utility will default to \"us-west-2\" so if you are using this tool for GovCloud or other partitions you will need to provide a region specific to that partition.\n- AWS Profiles and Account IDs - This is the set of aws profile names you wish to\n  add along with the corresponding AWS account ID. They are referenced as\n  `\u003cAWS_PROFILE\u003e:\u003cAWS_ACCOUNT_ID\u003e`. Use the flag name `--aws-profile-account`\n  with each set you wish to add.\n- Temporary AWS access keys - These should be given to you by an administrator\n  of the AWS account you are trying to access. The tool will prompt you for\n  the access key id and secret access key.\n\n1. Run the setup-new-user script\n\n   ```sh\n   setup-new-aws-user setup \\\n     --iam-user \u003cUSER\u003e \\\n     --iam-role \u003cROLE\u003e \\\n     --aws-region \u003cAWS_REGION\u003e \\\n     --aws-profile-account \u003cAWS_PROFILE1\u003e:\u003cAWS_ACCOUNT_ID1\u003e \\\n     --aws-profile-account \u003cAWS_PROFILE2\u003e:\u003cAWS_ACCOUNT_ID2\u003e\n   ```\n\n2. Enter the access keys generated when prompted.\n3. The script will open a window with a QR code, which you will use to configure a temporary one time password (TOTP).\n4. You'll then need to create a new entry in your 1Password account configure it with a TOTP field.\n5. Use 1Password to scan the QR code and hit save. New TOTP tokens should generate every 30 seconds.\n6. From here the tool will prompt you for 3 unique TOTP tokens. **NOTE Take care not to use the same token more than once, as this will cause the process to fail.**\n7. Once the tool has completed, you should be able to access the AWS account. You can run the following command filling in the `AWS_PROFILE` value\n\n   ```sh\n   aws-vault exec $AWS_PROFILE -- aws sts get-session\n   ```\n\n#### How `setup` modifies your ~/.aws/config\n\nWhile your AWS access keys are stored in a password protected keychain managed by `aws-vault`, the configuration for\nhow you should access AWS accounts lives in ~/.aws/config. The `setup-new-aws-user setup` tool creates new profiles in\n`~/.aws/config`. The first is the base profile containing your long lived AWS Access Keys and is tied to your IAM user\nand MFA device. Since these keys are long lived, you should be rotating them regularly with `aws-vault rotate`.\nThe second profile is the IAM role granting you elevated access to the AWS account. Typically these IAM roles are\nnamed `admin` or `engineer` and only uses temporary credentials leveraging AWS's Security Token Service (STS).\nBelow is an example config generated from this tool. Additional profiles will be similarly added and reference the\nbase profile.\n\n```ini\n[profile corp-id-base]\nmfa_serial=arn:aws:iam::123456789012:mfa/alice\nregion=us-west-2\noutput=json\n\n[profile corp-id]\nsource_profile=corp-id-base\nmfa_serial=arn:aws:iam::123456789012:mfa/alice\nrole_arn=arn:aws:iam::123456789012:role/admin\nregion=us-west-2\noutput=json\n```\n\n#### MFA Management\n\nThis tool will help create and enable a virtual MFA device. The interface for the MFA device is a QR code\nwhich will be shown to the user during setup. This QR code can be used with a password manager to provide the\nOne Time Passwords (OTP) values asked for in the script.\n\nIn the case where the user has a virtual MFA device already set up they can choose not to provision a new one.\nThis is done by issuing the `--no-mfa` flag on the command line in conjunction with the regular command from\nabove.\n\n### setup-new-aws-user add-profile\n\nBefore running this tool, you will need to following pieces of information\n\n- IAM role name - This is the IAM Role with permissions allowing access to AWS APIs\n  and services. This is usually something like `admin` or `engineer`. Use the flag\n  `--iam-role` with this value.\n- AWS Region - This utility will default to \"us-west-2\" so if you are using this tool for GovCloud or other partitions you will need to provide a region specific to that partition.\n- AWS profile - This is the name of the profile in your `~/.aws/config` profile\n  that you wish to use as the basis for adding new profiles. The `source_profile`\n  and `mfa_serial` is pulled from this profile.\n  Use the flag name `--aws-profile` with this value.\n- AWS Profiles and Account IDs - This is the set of aws profile names you wish to\n  add along with the corresponding AWS account ID. They are referenced as\n  `\u003cAWS_PROFILE\u003e:\u003cAWS_ACCOUNT_ID\u003e`. Use the flag name `--aws-profile-account`\n  with each set you wish to add.\n\n1. Run the setup-new-user script -\n\n   ```sh\n   setup-new-aws-user add-profile \\\n     --aws-profile \u003cAWS_PROFILE\u003e \\\n     --iam-role \u003cIAM_ROLE\u003e \\\n     --aws-region \u003cAWS_REGION\u003e \\\n     --aws-profile-account \u003cAWS_PROFILE1\u003e:\u003cAWS_ACCOUNT_ID1\u003e \\\n     --aws-profile-account \u003cAWS_PROFILE2\u003e:\u003cAWS_ACCOUNT_ID2\u003e\n   ```\n\n2. Once the tool has completed, you should be able to access the AWS account. You can run the following command filling in the `AWS_PROFILE` value\n\n   ```sh\n   aws-vault exec $AWS_PROFILE -- aws sts get-session\n   ```\n\n#### How `add-profile` modifies your ~/.aws/config\n\nWhile your AWS access keys are stored in a password protected keychain managed by `aws-vault`, the configuration for\nhow you should access AWS accounts lives in ~/.aws/config. The `setup-new-aws-user add-profile` tool creates new profiles in\n`~/.aws/config`. New profiles reference the `source_profile` and `mfa_serial` of the `--aws-profile` used in\nthe command and uses the IAM role granting you elevated access to the AWS account. Typically these IAM roles are\nnamed `admin` or `engineer` and only uses temporary credentials leveraging AWS's Security Token Service (STS).\nBelow is an example config generated from this tool. Additional profiles will be similarly added and reference the\nbase profile.\n\n```ini\n[profile corp-new]\nsource_profile=corp-id-base\nmfa_serial=arn:aws:iam::123456789012:mfa/alice\nrole_arn=arn:aws:iam::123456789012:role/engineer\nregion=us-west-2\noutput=json\n```\n\n**NOTE:** If you supply an aws-profile name that already exists in '~/.aws/config` this script will rewrite\nthat profile in your config.\n\n### setup-new-aws-user version\n\nTo get the version of the tool run:\n\n```sh\nsetup-new-aws-user version\n```\n\nIn development mode you may see the word `development` returned. Otherwise you should see the version of the tool\nas it was built by the release pipeline.\n\n## Development setup\n\n1. First, install these packages: `brew install pre-commit direnv go`\n2. Next, clone the project repository.\n3. Finally, run these commands inside the local repo: `direnv allow`\n4. The `.envrc` will be loaded if `direnv` is installed.\n\n### Testing\n\n#### Unit Tests\n\nRun pre-commit and Go tests\n\n```shell\npre-commit run -a\nmake test\n```\n\n#### Integration / End 2 End Testing\n\nFor testing, create a test IAM user so as not to interfere with your primary\nuser credentials and AWS config settings. The test user will need the\n`enforce-mfa` policy and permission to assume whichever role being assigned.\nGenerate an access key for the user, and use those when running the script. For\nthe AWS profile, do not use an existing profile name. You can use a dummy name\nfor the profile; it doesn't need to match the account alias. However, you must\nuse the real AWS account ID.\n\nExample:\n\n```shell\ngo run ./cmd setup --iam-role engineer --iam-user testuser --aws-profile-account test-profile-name:123456789012\n```\n\nAfter running the script, try a command to ensure the new profile works as\nexpected:\n\nExample (include AWS_VAULT_KEYCHAIN_NAME if the environment variable is not\nset):\n\n```shell\nAWS_VAULT_KEYCHAIN_NAME=login aws-vault exec test-profile-name -- aws sts get-caller-identity\n```\n\n### Troubleshooting\n\n#### User partially creates MFA device\n\nThe user might find themselves in an odd situation where the virtual MFA device was created but not assigned to the\nuser. This will prevent the user from coming back to the setup script and completing it. Here are steps to resolve if\nthe vMFA was created with no assigned user:\n\n```sh\naws iam list-virtual-mfa-devices\n# Find device with serial format of `arn:aws:iam::\u003cAWS_ACCOUNT_ID\u003e:mfa/\u003cIAM_USERNAME\u003e`\n# It may be listed without a User associated with it.\nSERIAL=arn:aws:iam::\u003cAWS_ACCOUNT_ID\u003e:mfa/\u003cIAM_USERNAME\u003e\naws iam delete-virtual-mfa-device --serial-number \"$SERIAL\"\n```\n\nIf the device was registered to a user it may need to be deactivated first, in which case its easier to find the\n`SERIAL` programatically:\n\n```sh\nexport USERNAME=somebody\nSERIAL=$(aws iam list-mfa-devices --user-name \"${USERNAME}\" | jq -r \".MFADevices[].SerialNumber\")\naws iam deactivate-mfa-device --user-name \"${USERNAME}\" --serial-number \"${SERIAL}\"\naws iam delete-virtual-mfa-device --serial-number \"$SERIAL\"\n```\n\nNow the device should be completely removed. Have them re-run the script.\n\n#### Publishing a release to Homebrew\n\nThis application is published to Homebrew and is done so via [goreleaser](https://goreleaser.com/) with the configuration defined in `.goreleaser.yml` and the `.github/workflows/release-macos.yml` GitHub Action that runs when a tag is created. To get the specifics of how this works, you can see the doc written [here](https://playbook.truss.dev/docs/developing/command-line-tools/HOW2GORELEASER). _hint_ Check 1password for Truss Infra GitHub credentials and a token attached. That's `GH_TOKEN` defined in the action.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrussworks%2Fsetup-new-aws-user","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrussworks%2Fsetup-new-aws-user","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrussworks%2Fsetup-new-aws-user/lists"}