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.
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.
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.
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: email@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.
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: firstname.lastname@example.org 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:
You can authenticate to each one with a different profile, enabling the ability to fast switch.
$ aws-google-auth -p dev Google username: email@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 = firstname.lastname@example.org
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
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
$ 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.
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
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_USERNAMEemail@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-dev to switch between roles.
In this example you can see that we use the stored account password for the
poc profiles, but will require a password for switching to the
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.
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!