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

and then SAML apps.

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

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.

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’

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.

You’ll find the “customerId”: parameter towards the bottom half of the 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

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

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

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.

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

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

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.

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.

…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.