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!
