{"id":16401288,"url":"https://github.com/ruimarinho/gsts","last_synced_at":"2025-04-05T07:02:29.527Z","repository":{"id":37169809,"uuid":"234448945","full_name":"ruimarinho/gsts","owner":"ruimarinho","description":"Obtain and store AWS STS credentials to interact with Amazon services by authenticating via G Suite SAML.","archived":false,"fork":false,"pushed_at":"2023-12-21T00:18:24.000Z","size":1875,"stargazers_count":201,"open_issues_count":6,"forks_count":34,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-14T10:03:16.203Z","etag":null,"topics":["amazon-services","authentication","aws","google","saml","sts","sts-credentials"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/ruimarinho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"ruimarinho"}},"created_at":"2020-01-17T01:52:57.000Z","updated_at":"2024-06-20T11:01:56.148Z","dependencies_parsed_at":"2023-02-09T13:16:01.400Z","dependency_job_id":"34cd0937-ee96-4c87-9413-a3e4caf4cc15","html_url":"https://github.com/ruimarinho/gsts","commit_stats":{"total_commits":187,"total_committers":11,"mean_commits":17.0,"dds":0.09625668449197866,"last_synced_commit":"a96dc8789c2fae65175f8ad01f37ca879c9e4518"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruimarinho%2Fgsts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruimarinho%2Fgsts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruimarinho%2Fgsts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruimarinho%2Fgsts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruimarinho","download_url":"https://codeload.github.com/ruimarinho/gsts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299829,"owners_count":20916190,"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":["amazon-services","authentication","aws","google","saml","sts","sts-credentials"],"created_at":"2024-10-11T05:29:55.475Z","updated_at":"2025-04-05T07:02:29.501Z","avatar_url":"https://github.com/ruimarinho.png","language":"JavaScript","funding_links":["https://github.com/sponsors/ruimarinho"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"images/logo/cover.png\" height=\"96\"\u003e\n  \u003cp align=\"center\"\u003eAWS STS credentials via Google Workspace\u003c/p\u003e\n\u003c/p\u003e\n\n`gsts` (short for `Google STS`) is an AWS CLI credential provider based on browser automation to seamlessly obtain and store AWS STS credentials to interact with Amazon services via Google Workspace SAML federation.\n\nThis allows you to configure AWS to rely on Google Workspace as your Identity Provider, moving the responsibility away from Amazon into Google to validate your login credentials (federated identity). This is a wildly popular solution when looking to offer Single-Sign On capabilities inside organizations.\n\nInstead of having to go through a flow tailored for the web browser, this tool enables developer productivity by keeping everything on the command line.\n\n#### Features:\n\n* Seamless integration with the `aws` cli tool for secure, continuous and non-interactive STS session renewals.\n* Only once headful design for interactively entering your Google Workspace credentials.\n* Full support for all 2FA methods as provided by Google, including Security Keys (Yubikeys, etc.).\n* Persistent headless re-authentication system.\n* Offers a quick action to open the AWS console from the command-line.\n* Support for AWS China (`aws-cn`) and AWS GovCloud (US) (`aws-us-gov`) ARNs.\n* Compatible with Amazon ECR and EKS.\n\n## Installation\n\n### macOS\n\n```shell\nbrew tap ruimarinho/tap\nbrew install gsts\n```\n\n### Other Platforms\n\nInstall the package via `npm`:\n\n```sh\nnpm install --global gsts\n```\n\nor via `yarn`:\n\n```\nyarn global add gsts\n```\n\n## Usage\n\n`gsts` is optimized to run as a [credential source](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html) provider for the `aws` cli. This ensures a seamless, automated and secure way of obtaining fresh session tokens without any kind of system interaction.\n\nThere are three key options or variables you need know about (you can read more about how to discover them below):\n\n1. Google's Identity Provider ID, or IdP ID (`--idp-id`).\n1. Google's Service Provider ID, or SP ID (`--sp-id`).\n2. The AWS ARN role(s) to authenticate with.\n\nAssuming the following scenario:\n\n1. You're using the `default` AWS profile name.\n2. You're using the default `~/.aws/config` for configuring the `aws` cli.\n3. The AWS ARN role you're trying to authenticate with is `arn:aws:iam::123456789012:role/role-name` and it's the only role you have access to.\n\nYou would then proceed to add the following `credential_process` entry to your `~/.aws/config` file under the `[default]` profile section:\n\n```sh\n[default]\ncredential_process = gsts --idp-id=\u003cyour_idp_id\u003e --sp-id=\u003cyour_sp_id\u003e\n```\n\nThe\n\n**Note**: if you are using a custom profile name other than `default` (for example, `sts`), then your configuration would slightly differ (notice the change to the `[profile \u003cname\u003e]` format):\n\n```sh\n[profile sts]\ncredential_process = gsts --idp-id=\u003cyour_idp_id\u003e --sp-id=\u003cyour_sp_id\u003e\n```\n\nIf your user has access to more than one AWS ARN role, you may specify which one to use on each profile by defining `--aws-role-arn`:\n\n```sh\n[default]\ncredential_process = gsts --idp-id=\u003cyour_idp_id\u003e --sp-id=\u003cyour_sp_id\u003e --aws-role-arn=arn:aws:iam::111111112222222:role/role-name\n```\n\nYou can then call any `aws` cli command and `gsts` will be spawned automatically:\n\n```sh\naws sts get-caller-identity\n```\n\nThat's it! With this setup, you're not supposed to call `gsts` manually ever. The first authentication will be performed directly on a headful browser where all of the authentication challenges generated by Google are natively supported (TOTP, Push, SMS, Security Keys, etc). Subsequent runs use an existing session to obtain fresh STS credentials every time it is executed.\n\n### In-memory (Cacheless) Credentials\n\nFor increased security, `gsts` supports passing over credentials to the `aws` cli without ever storing a copy of the credentials locally on its own cache dir via `--no-credentials-cache`.\n\nThe only downside is that every `aws` command will require re-authentication via `gsts`, which in some scenarios could generate too many authentication requests.\n\n### Configuration Settings Precedence\n\nTo avoid redundancy and potentially inconsistent configuration, such as having `gsts` obtain credentials for a different region than the one specified on the AWS profile settings, there are a few special `aws` cli environment variables that are automatically processed if defined.\n\nThe `gsts` configuration settings take precedence in the following order:\n\n1. `gsts` command line arguments.\n2. `gsts` environment variables (`GSTS_*`).\n3. `aws` cli configuration settings, [in the same order processed by the the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-precedence):\n   1. `aws` cli environment variables\n   2. `aws` cli configuration file (i.e. those in `~/.aws/config`)\n\n#### AWS CLI Supported Environment Variables\n\nEnvironment variables supported by `aws` cli and processed by `gsts`:\n\n* `AWS_CONFIG_FILE`: if defined, this environment variable overrides the behavior of `gsts` to read the config file from its default path at `~/.aws/config`.\n\n* `AWS_PROFILE`: if defined, this environment variable overrides the behavior of using the profile named `[default]` in the configuration and credentials files. You can override this environment variable by using the `GSTS_AWS_PROFILE` environment variable or the `--aws-profile` command line parameter.\n\n* `AWS_DEFAULT_REGION`: if defined, this environment variable overrides the value for the profile setting region. You can override this environment variable by using the `GSTS_AWS_REGION` environment variable or the `--aws-region` command line parameter.\n\n* `AWS_REGION`: if defined, this environment variable overrides the values in the environment variable `AWS_DEFAULT_REGION`\nand the profile setting region. You can override this environment variable by using the `GSTS_AWS_REGION` environment variable or the `--aws-region` command line parameter.\n\n#### AWS CLI Supported Profile Configuration Settings\n\nProfile configuration settings supported by `aws` cli and processed by `gsts`:\n\n* `duration_seconds`: the duration, in seconds, of the role session. You can override this profile configuration setting by using the `GSTS_AWS_SESSION_DURATION` environment variable or the `--aws-session-duration` command line parameter.\n\n* `region`: You can override this profile configuration setting by using the `GSTS_AWS_REGION`, `AWS_REGION` or `AWS_DEFAULT_REGION` environment variables as explained above or the `--aws-region` command line parameter.\n\nNotably, `output` is not supported since it could break `gsts` support for `credential_process` if its value is not `json` and setting `role_arn` makes the `aws` cli incompatible with `credential_process`.\n\n## Amazon ECR\n\nIf you'd like to automatically authenticate your Docker installation before pulling private images from Amazon ECR, you can use the fantastic [ECR Docker Credential Helper](https://github.com/awslabs/amazon-ecr-credential-helper) in combination with `gsts`.\n\n1. Install `docker-credential-helper-ecr` (on macOS, you can do it via Homebrew using `brew install docker-credential-helper-ecr`).\n2. Add the following config to your `~/.docker/config.json` file:\n\n    ```json\n    {\n      \"credHelpers\" : {\n        \"\u003cACCOUNT_ID\u003e.dkr.ecr.\u003cECR_REGION\u003e.amazonaws.com\" : \"ecr-login\"\n      }\n    }\n    ```\n\nThe config entry `ecr-login` maps to the binary `docker-credential-ecr-login` which must be available under your `$PATH`.\n\nThe next step a `docker pull` for an image from an ECR registry matching the string above is called, Docker will invisibly call `gsts` and perform authentication on your behalf.\n\n## Amazon EKS\n\nIf you'd like to automatically authenticate your Kubernetes authentication via Amazon EKS, add the following `exec` config under the `users` property of your `~/.kube/config` file:.\n\n```yaml\napiVersion: v1\nclusters:\n  - [...]\nkind: Config\npreferences: {}\nusers:\n- name: arn:aws:eks:us-west-1:111122223333:cluster/my-cluster\n  user:\n    exec:\n      apiVersion: client.authentication.k8s.io/v1\n      args:\n      - eks\n      - get-token\n      - --region\n      - eu-west-1\n      - --cluster-name\n      - my-cluster\n      command: aws\n      env:\n      - name: AWS_PROFILE\n        value: default\n      interactiveMode: Never\n      provideClusterInfo: false\n```\n\nIn this particularly case, the `AWS_PROFILE` env setting isn't strictly necessary as the default value would be used.\n\n## Quick Actions\n\n`gsts` offer a quick way to open the Amazon AWS console via the command line:\n\n```sh\ngsts console\n```\n\n## Reference\n\n```sh\n❯ gsts --help\n\nCommands:\n  gsts console  Authenticate via SAML and open Amazon AWS console in the default browser\n\nOptions:\n      --help                               Show help                                                                                         [boolean]\n      --version                            Show version number                                                                               [boolean]\n      --aws-profile                        AWS profile name to associate credentials with                                                   [required]\n      --aws-role-arn                       AWS role ARN to authenticate with\n      --aws-session-duration               AWS session duration in seconds (defaults to the value provided by the IDP, if set)                [number]\n      --aws-region                         AWS region to send requests to                                                                   [required]\n      --cache-dir                          Where to store cached data                                               [default: \"~/Library/Caches/gsts\"]\n      --clean                              Start authorization from a clean session state                                                    [boolean]\n      --force                              Force re-authorization even with valid session                                   [boolean] [default: false]\n      --idp-id                             Identity Provider ID (IdP ID)                                                                    [required]\n      --no-credentials-cache               Disable default behaviour of storing credentials in --cache-dir                                   [boolean]\n  -o, --output                             Output format                                                                     [choices: \"json\", \"none\"]\n      --playwright-engine                  Set playwright browser engine              [choices: \"chromium\", \"firefox\", \"webkit\"] [default: \"chromium\"]\n      --playwright-engine-executable-path  Set playwright executable path for browser engine\n      --playwright-engine-channel          Set playwright browser engine channel       [choices: \"chrome\", \"chrome-beta\", \"msedge-beta\", \"msedge-dev\"]\n      --sp-id                              Service Provider ID (SP ID)                                                             [string] [required]\n      --username                           Username to auto pre-fill during login\n  -v, --verbose                            Log verbose output                                                                                  [count]\n```\n\n## Discovery of IdP and SP IDs\n\nIf you're the admin of Google Workspace, after configuring the SAML application for AWS you can extract the SP ID by looking at the `service` parameter of the SAML AWS application page.\n\n\u003cimg src=\"images/google-workspace-sp-id.png\" width=\"800px\"\u003e\n\nThe IDP ID can be found under _Security \u003e Set up single sign-on (SSO) for SAML applications_ as the parameter `idpid`.\n\n\u003cimg src=\"images/google-workspace-idp-id.png\" width=\"800px\"\u003e\n\nIn case you are using a pre-configured AWS SAML application as traditionally available under the dotted menu on any Google app (Gmail, Calendar and so on) you can instead right-click the AWS icon and copy the link:\n\n\u003cimg src=\"images/google-workspace-aws-app.png\" width=\"300px\"\u003e\n\nThe copied URL will be in the format of `https://accounts.google.com/o/saml2/initsso?idpid=\u003cIDP_ID\u003e\u0026spid=\u003cSP_ID\u003e\u0026forceauthn=false`.\n\n## Troubleshooting\n\n**gsts conflicts with an alias from oh-my-zsh's git plugin**\n\n[ohmyzsh's git plugin](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/git) includes an alias named `gsts` as a shorthand for `git stash show --text`. You can either disable the `git` plugin entirely or, alternatively, add `unalias gsts` at the end of your dotfiles if you don't use this git command often.\n\n**\"Error when retrieving credentials from custom-process: Error: Failed to launch the browser process!\" when using the aws-cli with credential_process**\n\nAlthough seamingly unrelated to `gsts`, try unsetting `LD_LIBRARY_PATH` before calling it, like so:\n\n```bash\ncredential_process = bash -c \"unset LD_LIBRARY_PATH; gsts --aws-role-arn arn:aws:iam::123456789012:role/role-name --sp-id 12345 --idp-id A12bc34d5\"\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruimarinho%2Fgsts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruimarinho%2Fgsts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruimarinho%2Fgsts/lists"}