{"id":22998249,"url":"https://github.com/uswitch/stscreds","last_synced_at":"2025-08-14T00:31:55.680Z","repository":{"id":57495289,"uuid":"70900529","full_name":"uswitch/stscreds","owner":"uswitch","description":"Easily use temporary API keys with AWS","archived":false,"fork":false,"pushed_at":"2017-09-05T14:20:04.000Z","size":283,"stargazers_count":17,"open_issues_count":3,"forks_count":6,"subscribers_count":39,"default_branch":"master","last_synced_at":"2024-06-20T06:29:56.926Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/uswitch.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}},"created_at":"2016-10-14T10:36:18.000Z","updated_at":"2022-02-10T00:03:46.000Z","dependencies_parsed_at":"2022-08-31T12:02:23.623Z","dependency_job_id":null,"html_url":"https://github.com/uswitch/stscreds","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fstscreds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fstscreds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fstscreds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fstscreds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uswitch","download_url":"https://codeload.github.com/uswitch/stscreds/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229786999,"owners_count":18124014,"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-12-15T06:12:24.217Z","updated_at":"2024-12-15T06:12:24.884Z","avatar_url":"https://github.com/uswitch.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# stscreds\n\nstscreds makes it easier to work with temporary AWS API keys and, by extension, easier to stop using long-term credentials.\n\n## Rationale\n\nWorking with Amazon libraries often requires a developer to use an Access Key and Secret Key pair. Once created these don't expire (until you remove them).\n\nAmazon's [Security Token Service](http://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) can be used to request temporary credentials that automatically expire and must be requested/authenticated with an [MFA device](https://aws.amazon.com/iam/details/mfa/).\n\nFurther, through applying a policy to users, it's possible to restrict API access so that privileged operations are only allowed when the credentials were authenticated using an MFA device.\n\nThis tool helps make it easier to work with temporary credentials and shows a sample policy for restricting access to privileged APIs without MFA authentication.\n\n## Usage\nOnce installed you can use the tool as follows:\n\n```\n$ stscreds auth\nCurrent user: john.doe. Please enter MFA token: XXXXXX\nWrote credentials to /home/foo/.aws/credentials\n```\n\nWarning: the `~/.aws/credentials` is completely overwritten during `auth`. **If you use more than one profile you shouldn't use this tool**.\n\n## Installing\n\nYou can download binary releases (for Linux and Darwin) from GitHub: [https://github.com/uswitch/stscreds/releases](https://github.com/uswitch/stscreds/releases). Alternatively, you can also build from source using [Go](https://golang.org):\n\n```\n$ go get github.com/uswitch/stscreds\n```\n\n## Setup\n### IAM Policy\nAlthough stscreds can be used just to create temporary credentials, it's better to restrict API access to ensure only a handful of APIs are usable without using the credentials stscreds provides.\n\nThe following policy provides an example, allowing `sts:GetSessionToken`, `iam:GetUser` and `iam:ListMFADevices` (the 3 API methods stscreds uses to setup/authenticate) to users when authenticating using regular long-term credentials (such as those retrieved from the AWS Console). All other API operations require credentials generated with `sts:GetSessionToken`.\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": ...,\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"sts:GetSessionToken\",\n                \"iam:GetUser\",\n                \"iam:ListMFADevices\"\n            ],\n            \"Resource\": [\n                \"arn:aws:iam::*:user/${aws:username}\"\n            ]\n        },\n        {\n            \"Sid\": ...,\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"*\"\n            ],\n            \"Condition\": {\n                \"Bool\": {\n                    \"aws:MultiFactorAuthPresent\": \"true\"\n                }\n            },\n            \"Resource\": [\n                \"*\"\n            ]\n        }\n    ]\n}\n```\n\nThe above policy is just an example. It's a good idea to ensure your policies control access to privileged and/or destructive APIs. In the policy above the key part is to ensure you add a condition on `aws:MultiFactorAuthPresent`.\n\n### Configuring the tool\n\nstscreds uses `~/.stscreds/credentials` to store long-term API keys (these will often be the ones currently in use) and are the same keys generated/downloaded from the AWS Console.\n\n```\n$ stscreds init\nAWS Access Key: XXXXXXX\nAWS Secret Access Key: XXXXXXX\nSuccessfully wrote /home/foo/.stscreds/credentials\n```\n\n## Generating new keys\n\nOnce you've initialised using `stscreds init` above you'll only need to run `stscreds auth` from thereon. \n\n```\n$ stscreds auth\nCurrent user: first.last. Please enter MFA token: XXXXXX\nWrote credentials to /home/foo/.aws/credentials\n\n$ cat ~/.aws/credentials\n[default]\naws_access_key_id     = FOO\naws_secret_access_key = BAR\naws_session_token     = BAZ\n```\n\n## Reading credentials/Setting env variables\n\nIf you want to set environment variables from the stored `~/.aws/credentials` (having run `stscreds auth`) you can use the `read` command. For example, inside your `~/.bashrc` you could use:\n\n```\nexport AWS_ACCESS_KEY_ID=$(stscreds read aws_access_key_id)\nexport AWS_SECRET_ACCESS_KEY=$(stscreds read aws_secret_access_key)\nexport AWS_SESSION_TOKEN=$(stscreds read aws_session_token)\n```\n\n`read` will also ensure credentials are up-to-date; if credentials need to be refreshed you'll be prompted to enter another MFA token.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fstscreds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuswitch%2Fstscreds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fstscreds/lists"}