{"id":14064013,"url":"https://github.com/CurtisLusmore/AwsCredentialsManager","last_synced_at":"2025-07-29T17:31:37.103Z","repository":{"id":97623132,"uuid":"429708175","full_name":"CurtisLusmore/AwsCredentialsManager","owner":"CurtisLusmore","description":"A module for managing AWS CLI configuration and credentials","archived":false,"fork":false,"pushed_at":"2023-10-04T03:30:36.000Z","size":50,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-08-13T07:05:58.889Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CurtisLusmore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2021-11-19T07:33:49.000Z","updated_at":"2024-08-13T07:06:03.817Z","dependencies_parsed_at":"2024-08-13T07:18:41.681Z","dependency_job_id":null,"html_url":"https://github.com/CurtisLusmore/AwsCredentialsManager","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CurtisLusmore%2FAwsCredentialsManager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CurtisLusmore%2FAwsCredentialsManager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CurtisLusmore%2FAwsCredentialsManager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CurtisLusmore%2FAwsCredentialsManager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CurtisLusmore","download_url":"https://codeload.github.com/CurtisLusmore/AwsCredentialsManager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228032922,"owners_count":17858917,"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-13T07:03:37.627Z","updated_at":"2024-12-04T02:31:02.561Z","avatar_url":"https://github.com/CurtisLusmore.png","language":"PowerShell","readme":"# AwsCredentialsManager\r\n\r\n`AwsCredentialsManager` is a PowerShell module for managing [AWS CLI][0]\r\nconfiguration and credentials. It defines a naming convention for related\r\nprofiles, makes it easy to add, find and switch between profiles, and greatly\r\nsimplifies the process of refreshing temporary MFA credentials.\r\n\r\nFor example, at work you might have an IAM user and then several roles (one per\r\nenvironment) which require MFA to use. `AwsCredentialsManager` makes it easy to\r\nset up and manage the following profiles:\r\n\r\n* `work:iam` to represent your IAM user, defined by your CLI access key/secret,\r\n* `work:mfa` to represent your temporary MFA credentials, which uses `work:iam`\r\n    to obtain a session token,\r\n* `work:dev` to represent your role for the dev account, which uses `work:mfa`\r\n    as the source profile,\r\n* etc.\r\n\r\nThis module will help you to build and manage your AWS CLI `credentials` and\r\n`config` files to look something like the below:\r\n\r\n```\r\n# ~/.aws/credentials\r\n[work:iam]\r\naws_access_key_id = \u003cREDACTED\u003e\r\naws_secret_access_key = \u003cREDACTED\u003e\r\n[work:mfa]\r\naws_access_key_id = \u003cREDACTED\u003e\r\naws_secret_access_key = \u003cREDACTED\u003e\r\naws_session_token = \u003cREDACTED\u003e\r\n[home:iam]\r\naws_access_key_id = \u003cREDACTED\u003e\r\naws_secret_access_key = \u003cREDACTED\u003e\r\n\r\n# ~/.aws/config\r\n[profile work:mfa]\r\nmfa_device_arn = arn:aws:iam::000000000000:mfa/your.name\r\n[profile work:dev]\r\nrole_arn = arn:aws:iam::000000000000:role/PowerUsers\r\nsource_profile = work:mfa\r\nregion = ap-southeast-2\r\n[profile work:test]\r\nrole_arn = arn:aws:iam::111111111111:role/PowerUsers\r\nsource_profile = work:mfa\r\nregion = ap-southeast-2\r\n[profile work:staging]\r\nrole_arn = arn:aws:iam::222222222222:role/PowerUsers\r\nsource_profile = work:mfa\r\nregion = ap-southeast-2\r\n[profile home:project1]\r\nrole_arn = arn:aws:iam::999999999999:role/PowerUsers\r\nsource_profile = home:iam\r\nregion = ap-southeast-2\r\n```\r\n\r\nIt will also allow you to easily discover and switch between profiles, and\r\nmanage temporary MFA session tokens which last up to 36 hours.\r\n\r\n\r\n## Why This Module?\r\n\r\nThe major benefit of this module is the management of temporary MFA session\r\ntokens. The AWS CLI provides two ways of dealing with profiles which require\r\nMFA:\r\n\r\n### mfa_serial\r\n\r\nThe [`mfa_serial`][1] configuration setting allows you to specify an MFA device\r\nARN to use to generate temporary session tokens for a given role. Below is an\r\nexample of such a configuration setup:\r\n\r\n```\r\n~/.aws/credentials\r\n[iam]\r\naws_access_key_id = \u003cREDACTED\u003e\r\naws_secret_access_key = \u003cREDACTED\u003e\r\n\r\n~/.aws/config\r\n[profile myrole]\r\nrole_arn = arn:aws:iam::000000000000:role/PowerUsers\r\nsource_profile = iam\r\nmfa_serial = arn:aws:iam::000000000000:mfa/your.name\r\nduration_seconds = 3600\r\n```\r\n\r\nWhen performing CLI actions from the `myrole` profile, you will be prompted for\r\nyour MFA code and a temporary session token will be generated and cached for\r\nsubsequent CLI actions.\r\n\r\n```\r\n\u003e aws sts get-caller-identity\r\nEnter MFA code for arn:aws:iam::000000000000:mfa/your.name:\r\n{\r\n    \"UserId\": \"...\",\r\n    \"Account\": \"...\",\r\n    \"Arn\": \"...\"\r\n}\r\n```\r\n\r\nHowever, these session tokens will only be cached for [`duration_seconds`][2]\r\nseconds, which is typically capped to a maximum of 3600 (1 hour). This means\r\nthat a typical workday could involve 8 or more MFA code prompts.\r\n\r\n\r\n### sts get-session-token\r\n\r\nAn alternative is to use [`aws sts get-session-token`][3] to generate a\r\ntemporary session token, which is typically capped to a much more generous\r\nmaximum of 36 hours, meaning you will only be prompted for an MFA code once per\r\nday.\r\n\r\nThe issue with this method is that persisting the session token into your\r\ncredentials file or environment variables is left as an\r\n[exercise for the reader][4], which means that most users eventually end up\r\nimplementing a variation of this PowerShell module themselves.\r\n\r\n\r\n## How to Use\r\n\r\nEverything you need to know to install, configure and use this module is\r\ndescribed below.\r\n\r\n\r\n### Installation\r\n\r\nThis module can be installed from [PSGallery][5] with the following:\r\n\r\n```\r\n\u003e Install-Module -Name AwsCredentialsManager\r\n```\r\n\r\n### IAM Profiles\r\n\r\nTo get started, let's create a new IAM user for your \"work\" domain.\r\n\r\n```\r\n\u003e New-AwsIamUser -Domain work\r\nSupply values for the following parameters:\r\nAccessKeyId: ********************\r\nSecretAccessKey: ****************************************\r\n```\r\n\r\nAlternatively, your administrator may have sent your credentials in a standard\r\n`.csv` file which looks like this.\r\n\r\n```csv\r\nAccess key ID,Secret access key\r\n\u003cREDACTED\u003e,\u003cREDACTED\u003e\r\n```\r\n\r\nIn this case you can run the following.\r\n\r\n```\r\n\u003e New-AwsIamUser -Domain work -PathToCsv .\\your.name_accessKeys.csv\r\n```\r\n\r\nAfter running one of the above, you should now have an AWS profile named\r\n`work:iam`. You can confirm this by viewing the credentials file.\r\n\r\n```\r\n\u003e Get-Content ~/.aws/credentials\r\n[work:iam]\r\naws_access_key_id = \u003cREDACTED\u003e\r\naws_secret_access_key = \u003cREDACTED\u003e\r\n```\r\n\r\n\r\n### MFA Profiles\r\n\r\nSome AWS environments are configured to require MFA when using the CLI. In\r\nthese cases you will need to create a new profile which uses your IAM\r\ncredentials and an MFA code to obtain temporary session credentials.\r\n\r\nLet's add an MFA profile to our existing \"work\" domain.\r\n\r\n```\r\n\u003e New-AwsMfaUser -Domain work\r\nSupply values for the following parameters:\r\nDeviceArn: arn:aws:iam::000000000000:mfa/your.name\r\n```\r\n\r\nNote that the `-Domain` parameter will provide tab-completion values based on\r\nIAM profiles you have already configured. For example, you can type\r\n`New-AwsMfaUser -Domain` and then press `Tab` and it will automatically suggest\r\n`work` as a possible domain.\r\n\r\nYou should now have another AWS profile named `work:mfa`. You can confirm this\r\nby viewing the config file.\r\n\r\n```\r\n\u003e Get-Content ~/.aws/config\r\n[profile work:mfa]\r\nmfa_device_arn = arn:aws:iam::000000000000:mfa/your.name\r\n```\r\n\r\nThis profile won't exist in the credentials file until we acquire a session\r\ntoken, which we'll get to a bit later.\r\n\r\n\r\n### Assume-role Profiles\r\n\r\nMost AWS environments are configured such that permissions are granted via\r\nroles which you need to assume. You might have one role per project or per\r\ndeployment environment, so you will likely need to manage several such\r\nprofiles.\r\n\r\nLet's add an assume-role profile for our `dev` environment which requires MFA,\r\nso we can assume it from our `work:mfa` profile.\r\n\r\n```\r\n\u003e New-AwsAssumeRole -RoleName dev -User work:mfa\r\nSupply values for the following parameters:\r\nRoleArn: arn:aws:iam::000000000000:role/PowerUsers\r\nRegion: ap-southeast-2\r\n```\r\n\r\nNote that the `-User` parameter will provide tab-completion values based on\r\navailable IAM and MFA profiles you have already configured. There are also\r\n`-Iam` and `-Mfa` parameters as alternatives which will provide tab-completion\r\nvalues based on only IAM or MFA profiles respectively to make it even easier to\r\nfind the correct profile. For example, you can type `New-AwsAssumeRole -Mfa`\r\nand then press `Tab` and it will automatically suggest `work:mfa` as a possible\r\nsource profile.\r\n\r\nYou should now have another AWS profile named `work:dev`. You can confirm this\r\nby viewing the config file.\r\n\r\n```\r\n\u003e Get-Content ~/.aws/config\r\n[profile work:mfa]\r\nmfa_device_arn = arn:aws:iam::000000000000:mfa/your.name\r\n[profile work:dev]\r\nrole_arn = arn:aws:iam::000000000000:role/PowerUsers\r\nsource_profile = work:mfa\r\nregion = ap-southeast-2\r\n```\r\n\r\nThis profile will never appear in the credentials file because the credentials\r\nare provided by the linked source profile.\r\n\r\n\r\n### Setting the AWS Profile\r\n\r\nThe AWS Profile used by the CLI (when not specified explicitly via the\r\n`--profile` parameter) is specified by the `AWS_PROFILE` environment variable.\r\nThe module allows you to set this easily, by switching between available profiles, for example:\r\n\r\n```\r\n\u003e Set-AwsProfile -Domain work -All dev\r\n```\r\n\r\n`-All` refers to all available profiles belonging to the selected domain.\r\nTab completion is available for the domain, and the profile name within the domain.\r\nNote - you can use `-Iam`, `-Mfa` or `-AssumeRole` as alternate parameters to `-All`.\r\n\r\nFor example you can type `Set-AwsProfile -Domain work -AssumeRole` and then press\r\n`Tab` and it will automatically suggest `dev` as a possible profile.\r\n\r\nYou can confirm that the profile has been set by viewing the `AWS_PROFILE`\r\nenvironment variable.\r\n\r\n```\r\n\u003e $env:AWS_PROFILE\r\nwork:dev\r\n```\r\n\r\n\r\n### Updating Temporary Session Token via MFA\r\n\r\nIn order to use MFA profiles, or assume-role profiles which are backed by\r\nMFA profiles, you will need to acquire a temporary session token via MFA. Once\r\nyou have set the active AWS profile to an MFA or assume-role profile, you can\r\nupdate your session token with the following.\r\n\r\n```\r\n\u003e Update-AwsMfaCredentials\r\nSupply values for the following parameters:\r\nCode: ******\r\n```\r\n\r\nThis will create (or update) the MFA profile in the credentials file, which you\r\ncan confirm with the following.\r\n\r\n```\r\n\u003e Get-Content ~/.aws/credentials\r\n[work:iam]\r\naws_access_key_id = \u003cREDACTED\u003e\r\naws_secret_access_key = \u003cREDACTED\u003e\r\n[work:mfa]\r\naws_access_key_id = \u003cREDACTED\u003e\r\naws_secret_access_key = \u003cREDACTED\u003e\r\naws_session_token = \u003cREDACTED\u003e\r\n```\r\n\r\nYou can confirm that the session token provides access with the following.\r\n\r\n```\r\n\u003e aws sts get-caller-identity\r\n{\r\n    \"UserId\": \"...\",\r\n    \"Account\": \"...\",\r\n    \"Arn\": \"...\"\r\n}\r\n```\r\n\r\n\r\n[0]: https://aws.amazon.com/cli/\r\n[1]: https://docs.aws.amazon.com/sdkref/latest/guide/setting-global-mfa_serial.html\r\n[2]: https://docs.aws.amazon.com/sdkref/latest/guide/setting-global-duration_seconds.html\r\n[3]: https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/get-session-token.html\r\n[4]: https://aws.amazon.com/premiumsupport/knowledge-center/authenticate-mfa-cli/\r\n[5]: https://www.powershellgallery.com/packages/AwsCredentialsManager\r\n","funding_links":[],"categories":["PowerShell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCurtisLusmore%2FAwsCredentialsManager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCurtisLusmore%2FAwsCredentialsManager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCurtisLusmore%2FAwsCredentialsManager/lists"}