How to Use the Command 'aws-google-auth' (with Examples)

The aws-google-auth command is a CLI tool that facilitates the process of acquiring temporary AWS credentials by leveraging Google Apps as a federated Identity Provider (IdP) for Single Sign-On (SSO) access. This tool is particularly valuable for organizations that manage AWS environments and use Google Workspace (formerly Google Apps) to centralize user authentication. By employing this command, AWS users can obtain temporary security token service (STS) credentials, which enhances security by limiting the duration of access and ensuring that users authenticate using a federated system.

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

Code:

aws-google-auth -u example@example.com -I $GOOGLE_IDP_ID -S $GOOGLE_SP_ID -d 3600

Motivation:

When managing AWS environments, it is often necessary to ensure that users authenticate through a secure and centrally managed identity provider. Google SSO provides a robust authentication mechanism, and by linking it with AWS STS, organizations can enforce policies that enhance security. This is particularly crucial when temporary credentials need to be used for accessing AWS resources; controlling credential duration further limits potential misuse in case of credential exposure.

Explanation:

• -u example@example.com: The -u argument specifies the email address or username used for Google SSO authentication. This associates AWS access with the user account in Google Workspace.
• -I $GOOGLE_IDP_ID: The -I flag provides the Identity Provider ID, a unique identifier given by Google that helps in federating the authentication process with AWS.
• -S $GOOGLE_SP_ID: This flag denotes the Service Provider ID, which matches AWS’s identity as a service consumer in the SSO process.
• -d 3600: Here, -d is used to specify the duration for which the AWS credentials will remain valid. The value 3600 sets the duration to one hour (expressed in seconds).

Example Output:

Authenticated with SAML. Generated new credentials:
 -  AWS_ACCESS_KEY_ID: TEMP-ABCDEFGH123456789
 -  AWS_SECRET_ACCESS_KEY: +abcdEFGhijKlmnopqrSTUvwxYz1234567
 -  AWS_SESSION_TOKEN: AQoDYXdzEFh3LuA+pa7gE...
Credentials will expire at: YYYY-MM-DDTHH:MM:SSZ

Log in asking which role to use (in case of several available SAML roles)

Code:

aws-google-auth -u example@example.com -I $GOOGLE_IDP_ID -S $GOOGLE_SP_ID -d 3600 -a

Motivation:

AWS environments often involve multiple roles with varying permissions and responsibilities. In such cases, users may have access to several SAML roles within their organization, and it’s essential to allow them to choose the appropriate role for their task. This ensures that users have access only to the necessary permissions at any given time, optimizing security and operational efficiency.

Explanation:

• -u example@example.com: Specifies the email or username for Google SSO authentication.
• -I $GOOGLE_IDP_ID: Provides the Identity Provider ID for federated authentication.
• -S $GOOGLE_SP_ID: Indicates the Service Provider ID for AWS in the SSO setup.
• -d 3600: Sets the duration of the AWS credentials to one hour.
• -a: The -a flag prompts the user to select a role when multiple SAML roles are available. This ensures that the right access permissions are granted based on the selected role.

Example Output:

Multiple roles found. Please choose the role you wish to assume:
1: arn:aws:iam::123456789012:role/Admin
2: arn:aws:iam::123456789012:role/Developer
3: arn:aws:iam::123456789012:role/Viewer
Enter role selection: 

Resolve aliases for AWS accounts

Code:

aws-google-auth -u example@example.com -I $GOOGLE_IDP_ID -S $GOOGLE_SP_ID -d 3600 -a --resolve-aliases

Motivation:

AWS account IDs are typically represented as a series of numerical digits, which can be difficult to remember or associate directly with specific environments or applications. Using account aliases instead can make it much easier to identify and work with different AWS accounts. This functionality is invaluable for users who interact with multiple AWS environments, as it helps streamline the identification process.

Explanation:

• -u example@example.com: Username or email for authentication purposes.
• -I $GOOGLE_IDP_ID: Indicates the Google Identity Provider ID utilized for SSO.
• -S $GOOGLE_SP_ID: Service Provider ID corresponding to AWS.
• -d 3600: Duration for credential validity, set to one hour.
• -a: Prompts for role selection, encouraging users to choose the applicable permissions.
• --resolve-aliases: This option fetches AWS account aliases, if available, providing a more user-friendly identification of accounts beyond their standard IDs.

Example Output:

Attempting to resolve account aliases...
Available roles:
1: Admin (Account: dev-environment-123456)
2: Developer (Account: staging-environment-234567)
3: Viewer (Account: prod-environment-345678)
Enter role selection: 

Display help

Code:

aws-google-auth -h

Motivation:

Understanding the full capabilities and usage syntax of a command-line tool is crucial for maximizing its utility. The help option provides a comprehensive guide on how to use various arguments and options, thus empowering users to make the most out of the aws-google-auth tool. This is particularly useful for new users or those who need to refresh their knowledge of the command’s capabilities.

Explanation:

• -h: The help flag is used to print out a detailed help message, including descriptions of all available command-line options and usage instructions.

Example Output:

Usage: aws-google-auth [OPTIONS]

Options:
  -u, --username TEXT         The username used for authentication.
  -I, --idp-id TEXT           The Google Identity Provider ID.
  -S, --sp-id TEXT            The AWS Service Provider ID.
  -d, --duration INTEGER      The duration in seconds for which the temporary
                              credentials are valid.
  -a, --ask-role              Prompt to select a role when multiple are
                              available.
  --resolve-aliases           Resolve AWS account aliases.
  -h, --help                  Show this message and exit.

Conclusion:

The aws-google-auth tool provides a convenient and secure method to obtain temporary AWS credentials using Google SSO as a federated authentication system. By understanding its command-line options and use cases, users can enhance their workflow, enforce security best practices, and efficiently manage role-based access in AWS environments. Each specific use case, from role selection to alias resolution, serves to optimize and streamline AWS access management in organizations leveraging Google Workspace for identity management.