Using Google Apps SAML SSO to do one-click login to AWS

I never thought I’d be doing a blog post on AWS, but given the process documentation on Google’s side was missing a few crucial information, I saw a great opportunity.

I recently discovered that the Google Apps Admin Console lets you configure custom SAML apps to do one-click login to third party apps that support SAML SSO Authentication. One of the examples was AWS and I was curious to give it a shot. Once you understand it, it’s quite simple and I’m currently working on Active Directory Federation for a work project, but that’s a whole other animal for another blog post.

To start the setup, head over to the Google Apps Admin Console. Once you’re there navigate to the ‘Apps’ tab

Google Apps Admin Console

and then SAML apps.

Apps Tab

Once inside SAML Apps, go ahead and add a new app by clicking on the + icon and selecting Amazon Web Services.

On the next screen, make sure to select Option 2: Download IDP metadata and save the file on an easily accesible location

Google IDP Info

Once you have the IDP Metadata file saved, we’re going to create an IAM Identity Provider and an IAM Role in AWS. The role will designate what permissions will the SAML Federated user have within AWS.

To start, fire up the AWS Admin Console on a new tab and head to the IAM module. Once in the IAM Module, select Identity Providers from the left sidebar and then Create Provider. Select SAML from Provider Type and give it a name such as ‘GoogleApps’ (Note there are no spaces). When it asks you for the metadata document, go ahead and select from your hard drive the IDP Metadata file you downloaded from Google in the previous step. Verify the information, and finish off the wizard.

IAM Add Provider

With the provider configured, we’re now going to create a Role which will define the permissions. Click on the Roles tab on the left sidebar and Create a New Role. Whatever you name the Role will be what will be displayed next to the login name on the AWS Console, I went with GoogleSAML, but you can use Google or GoogleSSO or just SSO, or what ever you’d like. In Step 2, select ‘Role for Identity Provider Access’ and then ‘Grant Web Single Sign-On (WebSSO) access to SAML providers’ 

Create Role - Step 2

Once you select the WebSSO option, on Step 3 select the previously created Identity Provider and go ahead to the next step, you can leave the Establish Trust Relationship intact and advance to the next step. In Step 4 is where you define the policies your Federated Users will have. If you want to give Federated users specific permissions, create a Policy and then apply it to the Role. Creating a Policy is outside the scope of this blog, but you can read the AWS Documentation on it. To make things simple, I chose the AdministratorAccess policy, which grants Administrator Access to anyone logged in with a Google Federated credential inside my domain. Once you select the policy you’d like to apply, review your settings and Create the Role.

With the Role Created, it’s now time to get our hands a bit deeper. We’re going to use the Google Admin SDK APIs and the API Explorer to create a custom field in the Google Apps profile that will have the Role ARN and the Identity Provider ARN that will be passed on to AWS when doing the SAML Handshake.

The following scenario only applies if you have a few users (up to five) since you’ll be manually adding the Schema to each user, if you have more users, use the real API’s to bulk update the users.

To get the customerId:

If you only have one account in your Google Apps account and it’s the one you’re currently logged into, your customerId will be displayed in Step 2 of the SAML App Creation, where you downloaded the IDP Metadata. It is the string of characters in the SSO URL that follow idpid= (eg. https://accounts.google.com/o/saml2/idp?idpid=Ab1cde23f)

If you have more users, you’ll need to use the API or API Explorer and have Super Administrator privileges to extract their customerId.

On the API Explorer list, use the ‘directory.users.get‘ API to input the user’s email address under userKey, then Authorize and Execute. If you get a ‘Insufficient Permissions’ error. Click on the OAuth 2.0 toggle on the top right corner off and on again, that should fix the permissions. Make sure to grant access if prompted.

Customer ID Get

You’ll find the “customerId”: parameter towards the bottom half of the response.

 

Customer ID Get Response

Once you have the customerId, get back to the list of API’s and select the directory.schemas.insert API.
Insert the customerId of the Google Apps account, and then in the body put SAML as the SchemaName, then click the green + above to add a new array and put AWSAccountID as the fieldName, and STRING as the field type. I’ve included a video below that describes this process. Once you’re done, hit Execute.
(Note: If the request fails, make sure you’re authenticated and authorized – to make sure, click on the OAuth 2.0 toggle on the top right to ‘off’ and the back to ‘on’ and make sure to allow the API to make changes)

 

The response should look similar to this

Google API Explorer - Insert Schema

 

Now we need to populate the newly created fields with the AWS info. For that we’ll use the directory.users.update API
Input in the user’s email as the userKey, then select ‘customSchemas’ as a property, click Add, enter the name of the Schema (which should be SAML) on the first blank and then click the Add inside the parenthesis to add a field. Specify the Field Name (which should be AWSAccountID), and for the Text of the field you’re going to go back to AWS, grab the Role ARN followed by a ‘,’ and then the Identity Provider ARN. It should look something like this

arn:aws:iam::012345678:role/GoogleSAMLDemo,arn:aws:iam::012345678:saml-provider/GoogleAppsDemo

The video below shows describes the process in a visual way

Once you’re done, hit Execute.
(Note: If the request fails, make sure you’re authenticated and authorized – to make sure, click on the OAuth 2.0 toggle on the top right to ‘off’ and the back to ‘on’ and make sure to allow the API to make changes)

If your request was successful, you should see the newly added customSchema at the bottom of the response

Google APIs Explorer - User Update, Custom Schema

Repeat this step for every user you’d like to be able to login to AWS via the SAML SSO.

(Optional) If you’d like to really verify your customSchema was added to the profile; head back to the API Explorer list, use the ‘directory.users.get‘ API to input the user’s email address under userKey. This time use SAML as the customFieldMask and ‘custom’ as the projection. If your request was successful, the customSchema should be listed at the bottom of the request.

Now we’re ready for the final steps!

Head back to the Google Admin Page, Close the current New SAML App pop-up, refresh the page and click the + button to initiate the Wizard again. Select Amazon Web Services and you can skip Step 2. On Step 3, you can rename your module however you’d like. The Application Name is what will be shown to your users, so you can either keep it the same or change it to your liking. Leave Step 4 intact, and make sure the ACS URL and Entity ID are set to https://signin.aws.amazon.com/saml

Lastly, on Step 5 we’re going to map the field we just created to the SAML Request.

For the first row, choose Basic Information – Primary Email. On the Second Field, find the SAML option we created and on the next field select AWSAccountID

SAML Attribute Mapping

 

Go ahead and click finish. You now have your SAML App created! We now need to enable it. You can enable it for everyone on your organization or just a specific OU.

SAML App Page - Enable

 

Once your app is enabled, it’s time to test it! Go ahead and click on the External Launch icon.

SAML App Page - Launch

You should be redirected to the AWS Management Console and you should see that you’re authenticated with SAML credentials.

AWS Management Console with SAML Login

Great! Your SAML App now works. But how do your users get to it? At the top of every Google page there’s the app switcher. If you open it, and scroll down to the very bottom, you should see your newly created SAML App. If you click on it, it should take you to AWS with one click login.

App Switcher

You can also login using the new Google Apps User Hub (found at https://apps.google.com/user/hub) and you will see custom deployed apps the end of the list.

Google Apps User Hub

…and there you have it. One click login to AWS from anywhere in the Google ecosystem. You can hook any app that accepts SAML into Google, the setup will vary by app, but it should all be similar in a nutshell.

If you have any questions about what I covered in this article, feel free to leave a comment, shoot me an email, or a tweet (@fmisle) – and I’ll try to help as best as I can.

25 thoughts on “Using Google Apps SAML SSO to do one-click login to AWS

  1. Error: Your request included an invalid SAML response. To logout, click here.
    I have followed the steps you mentioned in the blog, but facing this error

    1. Hi lakhan, this is usually due to a misconfigured handshake in either AWS or Google. Without further look into your config, I can’t really be sure where.

      1. Thank you faisal, I forgot to configure following line “arn:aws:iam::012345678:role/” and because of this I was facing error

  2. Faisal –

    I have played around with writing Apps Script to do this, and got very close. Then, I saw a Google Apps Update Alert, that touted the new SAML changes. I followed Google’s instructions, and they were not very good.

    I saw your blog, and it is absolutely spot on! Thanks so much!!

    – Dave

  3. Does anyone know if and how it is possible to authenticate certain Google Apps users against AWS based on a group membership (in Google Apps)?
    Adding the role for each user would be to much effort for us.

    1. I know you can allow the app for certain groups, but not sure how to apply the token to people in those groups. I’ll do some research and get back to you.

      1. Hi Faisal –

        Did you ever get a chance to look into authenticating based on Google Apps group membership? Would be awesome if you could offer any insight since this would be a huge help to our organization.

  4. Faisal,

    Thank you very much for this tutorial, it was an incredible one !

    I have just a question, if I have multiple Amazon Web Services accounts, there is anyway that I choose the account before login in ?

    Thanks !

    1. Hi Marcus.
      Since the handshake is specific to each account, you’d need to create a SAML app for each account. You can then access them from the Google app launcher and click on whichever you want to login to.

  5. What a well written guide. Thanks a lot for this, it was extremely handy and saved me a lot of time trudging through the process myself.

  6. Hi All,

    Does anyone know how to associate Groups to roles? I have two roles on AWS and used Groups: Patch to patch the roles with group. But it turns out that the users in the group did not have the permissions to assume the roles. But when I associate Users with roles, it works.

  7. Fantastic. I am fiddling with getting Google Apps work as IdP for Office365. Got it working intermittently, but overall it is a fail. Do you think you could post a guide for Office365?

  8. Hi Faisal, great post, I was able to do sso integration between google and aws using your post. I have also added other employee using directory.users.update API but not sure who to revoke SSO integration for particular email id if employee leave the organization etc.

    Could you please throw some light how to rollback particular employee SSO access from google to AWS ?

  9. Has one been able to script the patching of user schemas so that giving access to several members isn’t such a manual process?

Leave a Reply