How to Set Up Federated Single Sign-On to AWS Using Google Apps

March 10, 2020: This blog post is out of date. Please refer to this post for updated info: How to set up federated single sign-on to AWS using Google Workspace

The AWS Security Blog has covered a variety of solutions for federating single sign-on (SSO) to the AWS Management Console. For example, How to Connect Your On-Premises Active Directory to AWS Using AD Connector, How to Set Up SSO to the AWS Management Console for Multiple Accounts by Using AD FS and SAML 2.0, and How to Implement a General Solution for Federated API/CLI Access Using SAML 2.0. Today, I am going to cover one SSO angle not yet covered on this blog: Google Apps.

Among the services offered to Google Apps for Work users is a Security Assertion Markup Language (SAML) 2.0–based SSO service. You can use this service to provide one-click SSO to your AWS resources by using your existing Google Apps credentials. For users to whom you grant SSO access, they will see an additional SAML app in your Google Apps account, as highlighted in the following screenshot. When your users click the SAML app, Google Apps authenticates and redirects them to the AWS Management Console. In this blog post, I will show you how you can use Google Apps to set up federated SSO to your AWS resources.

Solution overview

In this solution, you create a SAML identity provider (IdP) in AWS Identity and Access Management (IAM) to establish trust with your Google IdP in order to permit your Google Apps users to access the AWS Management Console. The AWS administrator delegates responsibility for authentication to a trusted IdP—in this case Google Apps—and uses SAML 2.0. This allows an IAM role to grant the federated user permissions to sign in to the AWS Management Console and access your AWS resources.

After you set up the solution, the process will follow the numbered steps in the preceding diagram:

1. The federated user clicks the Google Apps SSO link to AWS in their browser. If the user has not already logged in, he will go to the Google Apps account login portal.
2. The portal authenticates the user’s Google Apps credentials and then generates a SAML authentication response that includes assertions that identify the user and include attributes about the user. The portal sends this response to the user’s browser.
3. The user’s browser redirects to the AWS Sign-In endpoint and posts the SAML assertion.
4. AWS sign-in calls the AssumeRoleWithSAML API action (behind the scenes) to request temporary security credentials, and then creates a AWS Management Console sign-in URL using those credentials.
5. AWS returns the sign-in URL to the user’s browser as a redirect.
6. The user’s browser redirects to the AWS Management Console. Note that if the SAML authentication response includes attributes that map to multiple IAM roles, the user is prompted to select the IAM role to use for access to the console.

From the federated user’s perspective, the process happens transparently: the user starts at the Google Apps portal and ends up at the AWS Management Console, without ever having to supply yet another user name and password. The IAM policy attached to the IAM role determines which permissions the federated user has in the console.

I will now share and explain the specific step-by-step procedures you need to follow in order to set up federated SSO access via Google Apps.

The setup

Follow these top-level steps to set up federated SSO to your AWS resources by using Google Apps:

1. Get the SAML metadata from your Google Apps account.
2. Create an IdP in your AWS account.
3. Create an IAM role in your AWS account.
4. Add the AWS SAML attributes to your Google Apps user profile.
5. Set up the SAML app in Google Apps.
6. Grant user access.
7. Roll out to a wider user base.

The details of these steps compose the remainder of this blog post.

Step 1: Get the SAML metadata from your Google Apps account

First, let’s get the SAML metadata that contains essential information to enable your AWS account to authenticate the IdP and locate the necessary endpoint locations:

1. Log in to your Google Admin console with your super administrator credentials.

2. Click More Controls > Security > Set up single sign-on (SSO). The following screenshot shows the Set up single sign-on (SSO) page.

Make a note of the IdP ID at the end of the SSO URL. This is your Google customer ID and you will need to know this later. For the purposes of this blog post, I have anonymized my customer ID to be XXXXXXXXX, but yours will be an actual ID number.

3. Click Download next to IDP metadata under Option 2 to download the IdP metadata file. This is the format we need for the AWS IdP configuration.

Step 2: Create an IdP in your AWS account

Now, create an IAM IdP for Google Apps in order to establish trust between Google Apps and AWS.

1. Go to the IAM console and click Identity Providers. Click Create Provider and then select SAML from the Provider Type drop-down list (see the following screenshot). Type a name for the provider (such as GoogleApps), and then browse to the metadata file you downloaded in Step 1.

2. Click Next Step and then click Create. As the following screenshot shows, your newly created IdP will appear in the table of IdPs on the Identity Providers page.

3. Click the new IdP and note its Provider ARN, which you will need in Step 3.

Step 3: Create an IAM role in your AWS account

For users accessing the AWS Management Console, the IAM role that the user assumes governs access to AWS resources within your AWS account. The role is where you define what you allow a federated user to do after they sign in.

1. To create an IAM role, go to the IAM console. Click Roles > Create New Role. Type a name in the Role Name box, and then click Next Step.

2. On the Select Role Type page, choose Role for Identity Provider Access and then click Select next to Grant Web Single Sign-On (WebSSO) access to SAML providers.

3. On the next page (Establish Trust), select from the drop-down list the SAML IdP you created in the previous step, and then click Next Step.

You will be presented with the Trust Policy next, which grants the SAML IdP you created with permission to assume an IAM role from AWS STS. Click Next Step.

4. Next, you will see a list of policies that you can attach to the new IAM role, which will grant the permissions that the user logging in via Google Apps SSO will have. Select a policy to attach to the IAM role. You can update this policy at any time, if you want to add or remove permissions for the user. Click Next Step.

Note: For multiple users with different permissions, you can create multiple IAM roles, and the IAM role that a given user can assume is controlled from the Google Admin console through management of the user’s profile and organizations. For more information, see the last section in this blog post, “Roll out to a wider user base.”

5. Finally, you will see a review page for the role. Click Create Role to create the IAM role. After you create the new IAM role, locate it in the list of IAM roles, select it, and note its Role ARN, which you will need for the next step.

Step 4: Add the AWS SAML attributes to your Google Apps user profile

The first task before setting up the SAML app in your Google Apps account is to add the SAML attributes that the AWS Management Console expects in order to allow a SAML-based authentication to take place. You must add two SAML attributes:

• https://aws.amazon.com/SAML/Attributes/RoleSessionName
• https://aws.amazon.com/SAML/Attributes/Role

When configuring your SAML app in your Google Apps account, you will be prompted to provide attribute mappings from your Google Apps user profile. This includes details such as IAM roles available to the user and your AWS account ID. First, add these details as custom fields to the Google Apps user profile, which you can do by creating a JSON schema.

Note: You must create this JSON schema before creating the SAML app for your Google Apps account. If you create the JSON schema after creating the SAML app, the schema will not appear as a selectable option during configuration.

To create the JSON schema, you use the Schemas: Insert request from the Google Directory API that will take you to a Google developer webpage, allowing you to enter the required request fields and then click the AUTHORIZE AND EXECUTE button to have the https POST request to the Directory API automatically generated for you. This will require authentication.

On the Schemas: Insert page, enter the customer ID in the customerId field, which you noted when downloading the metadata file in Step 1. Then click inside the editing box for the request body, and in the right corner from the drop-down list, select Freeform Editor and paste the following text in the box.

{
    "fields":
      [
        {
            "fieldName": "role",
            "fieldType": "STRING",
            "readAccessType": "ADMINS_AND_SELF",    
            "multiValued": true
        }
    ],
    "schemaName": "SSO"
  }

Click AUTHORIZE AND EXECUTE. A completed Auth 2.0 Scopes dialog box will be presented. Click AUTHORIZE AND EXECUTE again and look for a successful http (200) response on the page. The resulting request will create a schema called SSO that allows you to add the names of one or more IAM roles to a Google Apps user profile, granting the user permission to assume those roles when signing in to the AWS account.

Note: If you see a “Permission denied” message when using the API, check that administrative API access has been enabled. For more information, see the Administrative APIs guide.

Having created the schema, you can add some SSO AWS role fields to your Google App user profile. To do this, use another Google Directory API request, Users: Patch.

From this web page, as before, use the Freeform Editor to paste the following text into the patch body. Be sure to replace the highlighted placeholder values with your values from the AWS Management Console that you noted earlier. Type your email address in the userKey field. Click AUTHORIZE AND EXECUTE, and look for a successful http (200) response.

{
  "customSchemas": 
  {
    "SSO": 
    {
      "role": [
      {
       "value": "<role ARN>,<provider ARN>",
       "customType": "Developer"
      }
     ]
    }
  }
}

Note: If you want multiple AWS accounts or IAM roles, you can add multiple accounts and roles in any combination. The user then will be prompted for the accounts and roles to use when they log in. For more information, see the last section in this blog post, “Roll out to a wider user base.”

Step 5: Set up the SAML app in Google Apps

Now that you have everything in place, you are ready to create your SAML app within your Google Apps account, which will provide the entry point for users to SSO into the AWS Management Console.

1. Enable SSO for the SAML app. Back in the Google Admin console as a super administrator, click Apps. Then click SAML apps (see the following screenshot).

2. Click the plus sign in the bottom right corner to add a new service or app for your domain, and then click Amazon Web Services, as shown in the following two screenshots.

3. Set up Google as your IdP. Google has provided an Amazon Web Services item that prepopulates much of the necessary information, including SSO URL and Entity ID values. These values include your IdP ID. We do not need to download the IdP metadata again because we did this earlier in Step 1, so click NEXT.

4. Provide basic information for AWS. You can now edit the Application Name and Description, and upload a 256-by-256 pixel logo. The information you supply dictates how the application appears to users. Click NEXT.

5. Provide service provider details. On the Service Provider Details page, values are prepopulated for the mandatory service provider fields: ACS URL (Assertion Consumer Service URL) and Entity ID. The Start URL box is optional and determines the URL to go to after successful authentication. If you leave this box blank, users will sign in to the main AWS Management Console’s home page. You could choose an alternative starting service page in the console. The Name ID is the user ID that will appear in the console after logging in. Click NEXT to proceed.

6. Provide attribute mapping. For attribute mapping, set the following values to map the user profile fields to the service provider attributes (also see the following screenshot):

• For https://aws.amazon.com/SAML/Attributes/RoleSessionName, choose Basic Information and then Primary Email (it is worth noting that RoleSessionName is the primary means of providing AWS CloudTrail traceability).
• For https://aws.amazon.com/SAML/Attributes/Role, choose the new Schema (SSO and role in this case) you created earlier.

Note: If you did not create this new schema before creating the SAML app, the schema will not appear here.

7. Click FINISH. You should see a dialog box that confirms that the configuration has been successful, as shown in the following screenshot.

You will see what the following screenshot shows. Click OK.

Review your settings. If you are satisfied with your settings, you can move on to the next section of this post.

Step 6: Grant user access

When you create the SAML app, by default it is turned off. This means that for users logged in to their Google Apps account, the SAML app will not be visible to them. To turn on the SAML app for AWS, go to your Google Admin console (using your super administrator credentials), click App, and then click SAML Apps. Select the actions from the right side of the page that the following screenshot shows.

If you do not want to activate this application for all users, you can take advantage of Google Apps organizational units and activate the SAML app for AWS for only a subset of users.

Note: Individual user profiles govern which AWS accounts and IAM roles a user can assume. For more information, see the last section in this blog post, “Roll out to a wider user base.”

For example, let’s say I have two simple example organizations, adminuser and generaluser (you can refer to the Google documentation for further details about creating these organizations). I want to configure access rights so that only users from the adminuser organization will have access to this SAML app, and here is how to do it:

1. Click ON for some organizations, and then click adminuser, as shown in the following screenshot.

2. Now click Override and click the sliding button. This prevents the adminuser organization from inheriting the master settings of the parent organization. Click APPLY.

3. You should see the confirmation message shown in the following screenshot. Click TURN ON. You now are ready to try using Google Apps to SSO to your AWS resources.

Any user from this organization (an administrative user, in this case) who logs in to their Google Apps account will see the new application in their Amazon Web Services SSO application list under More. In this case, the newly created application is represented by an orange cube (the optional icon I chose when creating the app) with the label Amazon Web Services, as shown in the following screenshot.

4. Clicking this AWS application will now handle all of the SAML-federated SSO for your Google Apps account and take you to the AWS Management Console (shown in the following screenshot) with the assigned AWS service permissions.

Step 7: Roll out to a wider user base

So far in this blog post, I have talked about setting up federated user access to AWS for a single Google Apps user (in other words, your own Google user account). Although this serves to demonstrate the steps involved in configuring your Google Apps and federated AWS access, you probably will be setting this up for many Google Apps users and potentially multiple AWS accounts. For example, you might have separate Development, QA, and Production AWS accounts, each with a number of different IAM roles with varying access permissions, all requiring access by specific groups of Google Apps users.

I have mentioned previously the use of organizations to restrict AWS SAML app access to specific organizations. In my example, I restricted this to users in the adminuser organization only. Specific access on a user-by-user basis to specific AWS accounts with specific permissions within those accounts (in other words, IAM roles) is controlled by the SSO attribute values assigned to each user’s profile. This is managed through the Google directory services API I used earlier to create the schema and assign attribute values. You can view directory services through the Google APIs Explorer.

Note: Operating at scale with many users may benefit from the creation of “helper” scripts to ease the management of larger numbers of users. Go to the Google Admin SDK for more information.

Let’s say that I have two accounts: Development (account number 111122223333) and Production (account number 444455556666). Each account has two IAM roles that allow dev-fulladmin, dev-readonly, and prd-readonly access, respectively. Let’s also say that I want a new user Bob to have dev-fulladmin and dev-readonly access to the Development account but only prd-readonly access to the Production account.

To make these access changes, I can add SSO fields to the Bob user profile, by using the Google Directory API Users: Patch request as we did before in Step 4. This time, however, I specify an email address for Bob in the userKey field and three role-entry fields as shown in the following patch body box.

{
"customSchemas":
{
"SSO":
{
"role": [
      {
         "value": "arn:aws:iam::111122223333:role/dev-fulladmin,arn:aws:iam::111122223333:saml-provider/GoogleApps",
         "customType": "DevAdmin"
      },
      {
         "value": "arn:aws:iam::111122223333:role/dev-readonly,arn:aws:iam::111122223333:saml-provider/GoogleApps",
         "customType": "DevReadOnly"
      },
      {
         "value": "arn:aws:iam::444455556666:role/prd-readonly,arn:aws:iam::444455556666:saml-provider/GoogleApps",
         "customType": "ProdReadOnly"
      }
    ]
   }
  }
}

Click AUTHORIZE AND EXECUTE, and look for a successful http (200) response. This has added these SSO AWS role permissions to the Bob user profile.

In this case, I have two accounts: account 111122223333 with two roles (dev-fulladmin and dev-readonly), and account 444455556666 with two roles (prd-fulladmin and prd-readonly). However, with this configuration, user profile Bob has only been granted permission to assume dev-fulladmin and dev-readonly from account 111122223333 and prd-readonly from account 444455556666. Now when user Bob is logged in to his Google Apps account and launches the AWS SAML app, he will be directed to the AWS Management Console as usual, but now he will be presented with the options to select the target account and the AWS IAM roles to which he is entitled, as shown in the following screenshot.

It is advantageous with multiple accounts and IAM roles to use role names that more clearly indicate the destination. For example, I have used IAM roles called dev-readonly and prd-readonly in the Development and Production accounts, respectively.

Ultimately, you can use the Google Directory API to manage permitted SSO attributes across your user base, in conjunction with organizations for granting access to the AWS Management Console. For managing bulk changes to user profile attributes, you can use the Google Directory API batch functionality. For more information, see Sending Batch Requests.

Summary

If you have followed the steps in this blog post, you should have configured your Google Apps directory and AWS accounts to allow SAML-based federated SSO for selected Google Apps users. If so, you are one step closer to reducing the number of user credentials that you must manage.

If you have comments about this post, please submit them in the “Comments” section below. If you have questions about the implementation detailed in this post, start a new thread on the IAM forum.

– William

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.