AWS CLI access with Google SSO using 'aws-google-auth'

In this post we explore how to set up a flexible and secure way to access the AWS CLI using the Open Source tool `aws-google-auth` developed and maintained by the team at Cevo.

Steve Mactaggart

At Cevo we access the AWS console through a Single Sign On (SSO) connection with our Google Apps identity provider. Further, our access is secured with Multi Factor Authentication (MFA) device tokens.

Accessing the AWS console through this method is pretty painless; simply click the SSO link in Google Apps and the browser handles all of the authentication negotiation allowing a pretty seamless access to the console.

But things become more complex when you want to get out of the browser - and into the command line.

There is currently no Google supplied authentication tool for the command line that allows negotiation with the sign on process.

Enter aws-google-auth

aws-google-auth is an Open Source tool developed by Cevo to solve the problem of acquiring AWS STS (temporary) credentials via Google Apps SAML Single Sign On.

The tool has been developed as a python library to provide strong cross platform support - supporting authentication from Windows, OSX and Linux based operating systems.

The idea for this project was inspired by the awesome work of wheniwork/keyme and aws-adfs, both of which we have used in the past and took as inspiration to develop the Google Apps authentication tool.

Installation

Like all python projects - installation can be as simple as executing:

$ pip install aws-google-auth

The advantage of python allows this installation process to work across all operating systems and devices.

If you do have any troubles installing the application, take a look at the project’s issues list for solutions.

Key Features

Easy interactive authentication

On your first run execution of the program you will be presented with an interactive set of prompts asking for your account details.

$ aws-google-auth 
Google username: test@example.com
Google IDP ID: 12345678
Google SP ID: ABCDEFGH
Google Password: 

aws-google-auth will then connect to the Google SSO servers and complete the authentication.

If aws-google-auth detects multiple accounts and roles, it will then prompt you to select the role from an available list.

$  aws-google-auth
Google username: test@example.com
Google IDP ID: 12345678
Google SP ID: ABCDEFGH
Google passweord:
[  1] arn:aws:iam::1234:role/Dev-Administrator
[  2] arn:aws:iam::5678:role/Demo-Administrator
[  3] arn:aws:iam::1256:role/Billing-ReadOnly
[  4] arn:aws:iam::1256:role/GuardDutyManager
[  5] arn:aws:iam::9876:role/Prod-Administrator
Type the number (1 - 5) of the role to assume: 

You simply select the role you want to assume, and this role will be assumed.

Assuming arn:aws:iam::1234:role/Dev-Administrator
Credentials Expiration: 2019-02-23 17:04:18+11:00

AWS Profile support

During your daily work you’ll probably need to switch between these accounts and roles, and no-one wants to have to remember the cryptic IDP and SP ID’s every time you need to re-authenticate.

To make this workflow easier, aws-google-auth can be set up to use the existing AWS CLI credentials files ~/.aws/config to store these settings.

By using the -p flag, you can specify the profile you want these credentials to be exported into.

For example, if you have 4 accounts:

  • poc
  • dev
  • prod
  • billing

You can authenticate to each one with a different profile, enabling the ability to fast switch.

$ aws-google-auth -p dev
Google username: test@example.com
Google IDP ID: 12345678
Google SP ID: ABCDEFGH
Google passweord:
[  1] arn:aws:iam::1234:role/Dev-Administrator
[  2] arn:aws:iam::5678:role/Demo-Administrator
[  3] arn:aws:iam::1256:role/Billing-ReadOnly
[  4] arn:aws:iam::1256:role/GuardDutyManager
[  5] arn:aws:iam::9876:role/Prod-Administrator
Type the number (1 - 5) of the role to assume: 1
Assuming arn:aws:iam::1234:role/Dev-Administrator
Credentials Expiration: 2019-02-23 17:11:53+11:00

You can see the details are cached here:

$ cat ~/.aws/config
[profile dev]
region = ap-southeast-2
google_config.ask_role = False
google_config.keyring = True
google_config.duration = 43200
google_config.google_idp_id = 12345678
google_config.role_arn = arn:aws:iam::1234:role/Dev-Administrator
google_config.google_sp_id = ABCDEFGH
google_config.u2f_disabled = False
google_config.google_username = test@example.com

But when you test these credentials they might not work.

$ aws s3 ls
Unable to locate credentials. You can configure credentials by running "aws configure".

This is because the credentials have been activated within the DEV profile.

To activate this profile you need to either export an environment variable or run the CLI commands with the profile flag.

$ aws s3 ls --profile dev
2018-03-21 21:18:44 blart
2018-12-16 00:55:53 bling
2019-02-07 10:24:23 bucket

or

$ export AWS_PROFILE=dev

$ aws s3 ls
2018-03-21 21:18:44 blart
2018-12-16 00:55:53 bling
2019-02-07 10:24:23 bucket

When you next need to authenticate you will simply be prompted for your password; aws-google-auth fills in the rest.

$ aws-google-auth -p dev
Google Password: 
Assuming arn:aws:iam::1234:role/Dev-Administrator
Credentials Expiration: 2019-02-23 17:17:31+11:00

Multi Factor Authentication (MFA)

As mentioned, at Cevo we not only use SSO for AWS authentication, but also have increased security through the use of Multi Factor Authentication tokens.

Google Apps support a multitude of different MFA methods - aws-google-auth supports most of these via the interactive CLI.

For example, on my account I have the Google Authenticator app enabled - so after authenticating with my password I am prompted via my phone app to approve this login.

$ aws-google-auth -p dev
Google Password: 
Open the Google App, and tap 'Yes' on the prompt to sign in ...
Assuming arn:aws:iam::1234:role/Dev-Administrator
Credentials Expiration: 2019-02-23 17:17:31+11:00

Cached SAML and passswords

The authentication process is actually a two step handshake between Google and AWS - the first part is the SAML authentication to the Google Apps service, with this SAML response we can then authenticate to the AWS service provider to complete the login.

For a short window, the SAML packet can be re-used without the need to re-authenticate. This can be really helpful if you select the wrong role and want to switch it quickly.

By default aws-google-auth caches the SAML packet to enable faster re-authentications. If it detects the SAML has expired, it will prompt for a full authentication workflow.

If you want to disable this feature, supply the --no-cache flag at the command line to ensure a full re-authentication is performed each time.

Similarly - entering your password every time at the command line might be something you want to avoid. By default this feature is disabled, but you can supply the -k flag to use a platform specific solution to store your passwords securely. On OSX for example, your password is stored in the system keychain tool.

Environment variable support

You also have the option to specify the main tool parameters as environment variables to speed up authentication even faster.

export GOOGLE_USERNAME=test@example.com
export GOOGLE_IDP_ID=12345678
export GOOGLE_SP_ID=ABCDEFGH

Then when you authenticate these values will be supplied as the answers to the interactive questions leaving you to only need to supply your password.

Alias for switching roles

Bringing all of these items together can give you a workflow to quickly switch and setup multiple role access through the use of some command alias.

By setting up some alias as follows:

alias aws-demo='unset AWS_PROFILE; aws-google-auth -k -p poc; export AWS_PROFILE=poc'
alias aws-dev='unset AWS_PROFILE; aws-google-auth -k -p dev; export AWS_PROFILE=dev'
alias aws-prod='unset AWS_PROFILE; aws-google-auth --no-cache -p prod; export AWS_PROFILE=prod'

You can simply type aws-demo or aws-dev to switch between roles.

In this example you can see that we use the stored account password for the demo and poc profiles, but will require a password for switching to the prod profile.

All the things

All of these features and more are listed in the parameters to tool itself.

$ aws-google-auth --help
usage: aws-google-auth [-h] [-u USERNAME] [-I IDP_ID] [-S SP_ID] [-R REGION]
                       [-d DURATION] [-p PROFILE] [-D] [-q] [--no-cache]
                       [--print-creds] [--resolve-aliases]
                       [--save-failure-html] [-a | -r ROLE_ARN] [-k] [-V]

Acquire temporary AWS credentials via Google SSO

optional arguments:
  -h, --help            show this help message and exit
  -u USERNAME, --username USERNAME
                        Google Apps username ($GOOGLE_USERNAME)
  -I IDP_ID, --idp-id IDP_ID
                        Google SSO IDP identifier ($GOOGLE_IDP_ID)
  -S SP_ID, --sp-id SP_ID
                        Google SSO SP identifier ($GOOGLE_SP_ID)
  -R REGION, --region REGION
                        AWS region endpoint ($AWS_DEFAULT_REGION)
  -d DURATION, --duration DURATION
                        Credential duration ($DURATION)
  -p PROFILE, --profile PROFILE
                        AWS profile (defaults to value of $AWS_PROFILE, then
                        falls back to 'sts')
  -D, --disable-u2f     Disable U2F functionality.
  -q, --quiet           Quiet output
  --no-cache            Do not cache the SAML Assertion.
  --print-creds         Print Credentials.
  --resolve-aliases     Resolve AWS account aliases.
  --save-failure-html   Write HTML failure responses to file for
                        troubleshooting.
  -a, --ask-role        Set true to always pick the role
  -r ROLE_ARN, --role-arn ROLE_ARN
                        The ARN of the role to assume
  -k, --keyring         Use keyring for storing the password.
  -V, --version         show program's version number and exit

We’d love to hear about how you are using this tool in your team’s workflow, and hope that you find this tool helpful in unlocking the AWS cli for AWS accounts that have federated sign-on through Google Apps.

Getting Involved

There is a small but vibrant community around the github project, contributions and ideas for features are most welcome.

Having troubles with the tool? Head over to the project’s issues page and check out information for resolving your problems.

If you’d like more information, or have any questions about this post or how to setup your AWS account authentication to be secure and flexible, please drop us a line!