Package: aws-google-auth
This command-line tool allows you to acquire AWS temporary (STS)
credentials using Google Apps as a federated (Single Sign-On, or SSO)
provider.SetupYou’ll first have to set up Google Apps as a SAML identity provider
(IdP) for AWS. There are tasks to be performed on both the Google Apps
and the Amazon sides; these references should help you with those
configurations:How to Set Up Federated Single Sign-On to AWS Using Google
AppsUsing Google Apps SAML SSO to do one-click login to
AWSIf you need a fairly simple way to assign users to roles in AWS
accounts, we have another tool calledGoogle AWS
Federatorthat might help you.Important DataYou will need to know Google’s assigned Identity Provider ID, and the ID
that they assign to the SAML service provider.Once you’ve set up the SAML SSO relationship between Google and AWS, you
can find the SP ID by drilling into the Google Apps console, underApps > SAML Apps > Settings for AWS SSO– the URL will include a
component that looks like...#AppDetails:service=123456789012...–
that number isGOOGLE_SP_IDYou can find theGOOGLE_IDP_ID, again from the admin console, viaSecurity > Set up singlesign-on(SSO)– theSSO URLincludes a
string likehttps://accounts.google.com/o/saml2/idp?idpid=aBcD01AbCwhere the last bit (after the=) is the IDP ID.InstallationYou can install quite easily viapip, if you want to have it on your
local system:# For basic installationlocalhost$sudopipinstallaws-google-auth# For installation with U2F supportlocalhost$sudopipinstallaws-google-auth[u2f]NoteIf using ZSH you will need to quote the install, as below:localhost$sudopipinstall"aws-google-auth[u2f]"If you don’t want to have the tool installed on your local system, or if
you prefer to isolate changes, there is a Dockerfile provided, which you
can build with:# Perform local buildlocalhost$cd..../aws-google-auth&&dockerbuild-taws-google-auth.# Use the Docker Hub versionlocalhost$dockerpullcevoaustralia/aws-google-authDevelopmentIf you want to develop the AWS-Google-Auth tool itself, we thank you! In order
to help you get rolling, you’ll want to install locally with pip. Of course,
you can use your own regular workflow, with tools likevirtualenv.# Install (without U2F support)pipinstall-e.# Install (with U2F support)pipinstall-e.[u2f]We welcome you to review ourcode of conductandcontributingdocuments.Usage$aws-google-auth-husage:aws-google-auth[-h][-uUSERNAME][-IIDP_ID][-SSP_ID][-RREGION][-dDURATION][-pPROFILE][-D][-q][--bg-responseBG_RESPONSE][--saml-assertionSAML_ASSERTION][--no-cache][--print-creds][--resolve-aliases][--save-failure-html][--save-saml-flow][-a|-rROLE_ARN][-k][-l{debug,info,warn}][-V]AcquiretemporaryAWScredentialsviaGoogleSSOoptionalarguments:-h,--helpshowthishelpmessageandexit-uUSERNAME,--usernameUSERNAMEGoogleAppsusername($GOOGLE_USERNAME)-IIDP_ID,--idp-idIDP_IDGoogleSSOIDPidentifier($GOOGLE_IDP_ID)-SSP_ID,--sp-idSP_IDGoogleSSOSPidentifier($GOOGLE_SP_ID)-RREGION,--regionREGIONAWSregionendpoint($AWS_DEFAULT_REGION)-dDURATION,--durationDURATIONCredentialduration(defaultstovalueof$DURATION,thenfallsbackto43200)-pPROFILE,--profilePROFILEAWSprofile(defaultstovalueof$AWS_PROFILE,thenfallsbackto'sts')-D,--disable-u2fDisableU2Ffunctionality.-q,--quietQuietoutput--bg-responseBG_RESPONSEOverridedefaultbgresponsechallengetoken($GOOGLE_BG_RESPONSE).--saml-assertionSAML_ASSERTIONBase64encodedSAMLassertiontouse.--no-cacheDonotcachetheSAMLAssertion.--print-credsPrintCredentials.--resolve-aliasesResolveAWSaccountaliases.--save-failure-htmlWriteHTMLfailureresponsestofilefortroubleshooting.--save-saml-flowWriteallGETandPUTrequestsandHTMLresponsesto/fromGoogletofilesfortroubleshooting.-a,--ask-roleSettruetoalwayspicktherole-rROLE_ARN,--role-arnROLE_ARNTheARNoftheroletoassume($AWS_ROLE_ARN)-k,--keyringUsekeyringforstoringthepassword.-l{debug,info,warn},--log{debug,info,warn}Selectloglevel(default:warn)-V,--versionshowprogram'sversionnumberandexitNoteIf you want a longer session than the AWS default 3600 seconds (1 hour)
duration, you must also modify the IAM Role to permit this. Seethe AWS documentationfor more information.Native PythonExecuteaws-google-authYou will be prompted to supply each parameterNoteYou can skip prompts by either passing parameters to the command, or setting the specified Environment variables.Via DockerSet environment variables for anything listed in Usage with($VARIABLE)after command line option:GOOGLE_USERNAME,GOOGLE_IDP_ID, andGOOGLE_SP_ID(see above under “Important Data” for how to find the last two; the first one is usually your email address)AWS_PROFILE: Optional profile name you want the credentials set for (default is ‘sts’)ROLE_ARN: Optional ARN of the role to assumeFor Docker:docker run-it-eGOOGLE_USERNAME-eGOOGLE_IDP_ID-eGOOGLE_SP_ID-eAWS_PROFILE-eROLE_ARN-v~/.aws:/root/.awscevoaustralia/aws-google-authYou’ll be prompted for your password. If you’ve set up an MFA token for
your Google account, you’ll also be prompted for the current token
value.If you have a U2F security key added to your Google account, you won’t
be able to use this via Docker; the Docker container will not be able to
access any devices connected to the host ports. You will likely see the
following error during runtime: “RuntimeWarning: U2F Device Not Found”.If you have more than one role available to you (and you haven’t set up ROLE_ARN),
you’ll be prompted to choose the role from a list.Feeding password from stdinTo enhance usability when using third party tools for managing passwords (aka password manager) you can feed data inaws-google-authfromstdin.When receiving data fromstdinaws-google-authdisables the interactive prompt and usesstdindata.Before#82, all interactive prompts could be fed fromstdinalready apart from theGoogle Password:prompt.Example usage:` $password-managershow password |aws-google-authGoogle Password: MFA token: Assumingarn:aws:iam::123456789012:role/adminCredentials Expiration: ... `Note:this feature is intended for password manager integration, not for passing passwords from command line.
Please use interactive prompt if you need to pass the password manually, as this provide enhanced security avoid
password leakage to shell history.Storage of profile credentialsThrough the use of AWS profiles, using the-por--profileflag, theaws-google-authutility will store the supplied username, IDP and SP details in your./aws/configfiles.When re-authenticating using the same profile, the values will be remembered to speed up the re-authentication process.
This enables an approach that enables you to enter your username, IPD and SP values once and then after only need to re-enter your password (and MFA if enabled).Creating an alias as below can be a quick and easy way to re-authenticate with a simple command shortcut.` aliasaws-development='unsetAWS_PROFILE;aws-google-auth-I$GOOGLE_IDP_ID-S$GOOGLE_SP_ID-u$USERNAME-paws-dev; exportAWS_PROFILE=aws-dev'`Or, if you’ve alredy established a profile with valid cached values:` aliasaws-development='unsetAWS_PROFILE;aws-google-auth-paws-dev; exportAWS_PROFILE=aws-dev'`Notes on AuthenticationGoogle supports a number of 2-factor authentication schemes. Each of these
results in a slightly different “next” URL, if they’re enabled, duringdo_loginGoogle controls the preference ordering of these schemes in the case that
you have multiple ones defined.The varying 2-factor schemes and their representative URL fragments handled
by this tool are:MethodURL FragmentNo second factor(none)TOTP (eg GoogleAuthenticator
or Authy).../signin/challenge/totp/...SMS (or voicecall).../signin/challenge/ipp/...SMS (or voicecall) with
number
submission.../signin/challenge/iap/...Google Prompt(phone app).../signin/challenge/az/...Security key(eg yubikey).../signin/challenge/sk/...Dual prompt(Validate 2FA ).../signin/challenge/dp/...Backup code(printed codes)... (unknown yet) ...AcknowledgmentsThis work is inspired bykeyme– their digging into the guts of how Google SAML auth works is what’s
enabled it.The attribute management and credential injection into AWS configuration files
was heavily borrowed fromaws-adfs <https://github.com/venth/aws-adfs>