aws-google-auth

Log in with Google SSO using the specified username IDP and SP identifiers and set the credentials duration to one hour

$ aws-google-auth [[-u|--username]] [example@example.com] [[-I|--idp-id]] [$GOOGLE_IDP_ID] [[-S|--sp-id]] [$GOOGLE_SP_ID] [[-d|--duration]] [3600]

$ aws-google-auth [[-u|--username]] [example@example.com] [[-I|--idp-id]] [$GOOGLE_IDP_ID] [[-S|--sp-id]] [$GOOGLE_SP_ID] [[-d|--duration]] [3600] [[-a|--ask-role]]

$ aws-google-auth [[-u|--username]] [example@example.com] [[-I|--idp-id]] [$GOOGLE_IDP_ID] [[-S|--sp-id]] [$GOOGLE_SP_ID] [[-d|--duration]] [3600] [[-a|--ask-role]] --resolve-aliases

$ aws-google-auth [[-h|--help]]

aws-google-auth [--profile PROFILE] [--role ROLE_ARN] [--sso-url URL] [--console] [--region REGION] [--force] [--clear-cache] [--headless] [--verbose] [--version] [--help]

--profile PROFILE
    Specifies the AWS credential profile to update. If not provided, it defaults to the default profile.

--role ROLE_ARN
    The ARN of the specific AWS role to assume. If omitted, the tool will present a list of available roles from the Google SSO page for selection.

--sso-url URL
    Overrides the default Google SSO URL used for authentication. This is typically the SAML endpoint configured in Google Workspace.

--console
    After successful authentication, opens the AWS management console in your default web browser using the obtained temporary credentials.

--region REGION
    Specifies the AWS region for the temporary credentials. This might be necessary if your SSO setup is region-specific or if you need to use credentials for a particular region.

--force
    Forces a re-authentication process even if valid cached credentials exist.

--clear-cache
    Clears any cached Google session cookies and temporary AWS credentials.

--headless
    Runs the browser automation in headless mode (without a visible browser window). Requires a compatible WebDriver (e.g., ChromeDriver) installed.

--verbose
    Enables verbose logging, providing more detailed output for debugging purposes.

--version
    Displays the version of the aws-google-auth tool.

--help
    Shows the command's help message and exits.

aws-google-auth is a Python utility that streamlines the authentication process for the AWS Command Line Interface (CLI) when an organization uses Google Workspace (formerly G Suite) for Identity Provider (IdP) based Single Sign-On (SSO) through SAML.

Instead of manually obtaining temporary AWS credentials from the AWS console, this tool automates the process. It simulates a browser-based login flow to Google, then navigates to the AWS SSO endpoint, retrieves temporary AWS Access Key ID, Secret Access Key, and Session Token. These credentials are then automatically stored in your ~/.aws/credentials file, allowing subsequent AWS CLI commands to use these temporary credentials without requiring manual setup. This enhances security by using short-lived credentials and improves developer productivity by simplifying authentication.

Requires Python 3.6+ and associated dependencies.

A compatible web browser (like Chrome, Firefox) and its corresponding WebDriver (e.g., ChromeDriver, geckodriver) must be installed and accessible in your system's PATH, especially for headless mode.

The tool interacts with Google and AWS SSO pages, so changes to these pages' layouts or authentication flows by Google or AWS may temporarily break the tool until updated.

Your Google Workspace and AWS accounts must be properly configured for SAML-based SSO.

It relies on browser automation, which can sometimes be flaky due to network issues or dynamic web content.

aws-google-auth can be configured using environment variables or a configuration file (e.g., ~/.aws/config or a dedicated config file) to set default values for SSO URL, region, and other options, avoiding repetitive command-line arguments.

The tool implements a caching mechanism for both Google session cookies and AWS temporary credentials. This means that once you authenticate, subsequent runs within a configured session duration might not require re-logging into Google, speeding up credential refreshing.

It uses browser automation libraries (like Selenium WebDriver) to interact with the web pages, filling forms, and clicking buttons to complete the SSO flow. This requires a browser and its respective WebDriver to be installed on the system.

aws-google-auth was developed as an open-source solution to address the growing need for simplified AWS CLI authentication within organizations leveraging Google Workspace for their identity management. Prior to tools like this, users often had to manually log into the AWS console via their IdP, obtain temporary credentials, and then configure them for the AWS CLI, a repetitive and error-prone process. The tool aims to automate this, improving developer workflow and promoting the use of short-lived credentials for enhanced security, reducing the risk associated with long-term static credentials. It gained traction in the cloud community for its specific focus on Google-AWS integration.

aws(1), sts(1), saml2aws(1)