Using puppeteer executable for GSTS

GSTS lets you use Google Workspace as a credential provider for your AWS CLI. It drives a browser in the background to complete the SAML login, then writes short-lived credentials for the role you asked for. If you manage multiple AWS accounts in one organization, Google Workspace SAML federation validates the login for all of them, so the AWS CLI SAML login is the same flow everywhere.

First, install GSTS:

npm install --global gsts

Then add this credential_process line to your ~/.aws/config:

[default]
credential_process = gsts --idp-id=<your_idp_id> --sp-id=<your_sp_id> --aws-role-arn=arn:aws:iam::111111112222222:role/role-name

The first login fails when Playwright has no browser installed

GSTS uses MS Playwright to open a browser and handle the authentication. On my first login it failed, because Playwright had never downloaded a browser on that machine. The error looked like this:

Error when retrieving credentials from custom-process: [...] ERROR gsts: browserType.launchPersistentContext: Executable doesn't exist at [...]/Caches/ms-playwright/chromium-1105/chrome-mac/Chromium.app/Contents/MacOS/Chromium
╔═════════════════════════════════════════════════════════════════════════╗
║ Looks like Playwright Test or Playwright was just installed or updated. ║
║ Please run the following command to download new browsers:              ║
║                                                                         ║
║     npx playwright install                                              ║
║                                                                         ║
║ <3 Playwright Team                                                      ║
╚═════════════════════════════════════════════════════════════════════════╝

Point GSTS at a Chromium executable path you already have

The message tells you to run npx playwright install, which downloads a second browser. I already had Puppeteer installed for some automation processes, and I prefer working with that instead of installing Playwright for this one thing. GSTS takes a flag for the browser binary, so you can pass any Chromium executable path: the one from puppeteer.executablePath(), or the Homebrew Chromium on macOS. Add --playwright-engine-executable-path /opt/homebrew/bin/chromium to the end of the credential command:

[profile sts]
credential_process = gsts --idp-id=<your_idp_id> --sp-id=<your_sp_id> --aws-role-arn=arn:aws:iam::111111112222222:role/role-name  --playwright-engine-executable-path /opt/homebrew/bin/chromium

This way, you can use your existing Chromium installation and avoid setting up Playwright separately.

TL;DR

GSTS simplifies using Google Workspace as a credential provider for AWS CLI, especially when managing multiple AWS accounts. Installation is straightforward, but you might encounter a hiccup with Playwright during the first-time setup. A quick fix is to use Puppeteer if you have it already installed, saving you the hassle of setting up another browser automation tool.