How to set up IAM federation using Google Workspace
August 10, 2022: This blog post has been updated to reflect the new name of AWS Single Sign-On (SSO) – AWS IAM Identity Center. Read more about the name change here.
March 16, 2022: The title and the opening section of this blog post has been updated.
Federating your external identity provider (IdP) to AWS is a best practice. The simplest way to federate into AWS is with AWS IAM Identity Center. With IAM Identity Center, you configure federation once and manage access to all of your AWS accounts centrally. See this blog post on the process of setting up Google Workspace as an external IdP in IAM Identity Center. Previously, customers configured federation using AWS Identity and Access Management (IAM) which requires configuring your SAML identity provider for each AWS account. In this blog post, we will show you how to configure federation with Google Workspace if you are using AWS IAM federation.
In this solution, you will create a SAML identity provider in IAM to establish a trusted communication channel across which user authentication information may be securely passed with your Google IdP in order to permit your Google Workspace users to access the AWS Management Console. You, as the AWS administrator, delegate responsibility for user authentication to a trusted IdP, in this case Google Workspace. Google Workspace leverages SAML 2.0 messages to communicate user authentication information between Google and your AWS account. The information contained within the SAML 2.0 messages allows an IAM role to grant the federated user permissions to sign in to the AWS Management Console and access your AWS resources. The IAM policy attached to the role they select determines which permissions the federated user has in the console.
Figure 1 illustrates the login process for IAM federation. From the federated user’s perspective, this process happens transparently: the user starts at the Google Workspace portal and ends up at the AWS Management Console, without having to supply yet another user name and password.
- The portal verifies the user’s identity in your organization. The user begins by browsing to your organization’s portal and selects the option to go to the AWS Management Console. In your organization, the portal is typically a function of your IdP that handles the exchange of trust between your organization and AWS. In Google Workspace, you navigate to https://myaccount.google.com/ and select the nine dots icon on the top right corner. This will show you a list of apps, one of which will log you in to AWS. This blog post will show you how to configure this custom app.
- The portal verifies the user’s identity in your organization.
- The portal 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 client browser. Although not discussed here, you can also configure your IdP to include a SAML assertion attribute called SessionDuration that specifies how long the console session is valid. You can also configure the IdP to pass attributes as session tags.
- The client browser is redirected to the AWS single sign-on endpoint and posts the SAML assertion.
- The endpoint requests temporary security credentials on behalf of the user, and creates a console sign-in URL that uses those credentials.
- AWS sends the sign-in URL back to the client as a redirect.
- The client browser is redirected to the AWS Management Console. If the SAML authentication response includes attributes that map to multiple IAM roles, the user is first prompted to select the role for accessing the console.
The list below is a high-level view of the specific step-by-step procedures needed to set up federated single sign-on access via Google Workspace.
Follow these top-level steps to set up federated single sign-on to your AWS resources by using Google Apps:
- Download the Google identity provider (IdP) information.
- Create the IAM SAML identity provider in your AWS account.
- Create roles for your third-party identity provider.
- Assign the user’s role in Google Workspace.
- Set up Google Workspace as a SAML identity provider (IdP) for AWS.
- Test the integration between Google Workspace and AWS IAM.
- Roll out to a wider user base.
Detailed procedures for each of these steps compose the remainder of this blog post.
Step 1. Download the Google identity provider (IdP) information
First, let’s get the SAML metadata that contains essential information to enable your AWS account to authenticate the IdP and locate the necessary communication endpoint locations:
- Log in to the Google Workspace Admin console
- From the Admin console Home page, select Security > Settings > Set up single sign-on (SSO) with Google as SAML Identity Provider (IdP).
- Choose Download Metadata under IdP metadata.
Step 2. Create the IAM SAML identity provider in your account
Now, create an IAM IdP for Google Workspace in order to establish the trust relationship between Google Workspace and your AWS account. The IAM IdP you create is an entity within your AWS account that describes the external IdP service whose users you will configure to assume IAM roles.
- Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
- In the navigation pane, choose Identity providers and then choose Add provider.
- For Configure provider, choose SAML.
- Type a name for the identity provider (such as GoogleWorkspace).
- For Metadata document, select Choose file then specify the SAML metadata document that you downloaded in Step 1–c.
- Verify the information that you have provided. When you are done, choose Add provider.
- Document the Amazon Resource Name (ARN) by viewing the identity provider you just created in step f. The ARN should looks similar to this:
Step 3. Create roles for your third-party Identity Provider
For users accessing the AWS Management Console, the IAM role that the user assumes allows access to resources within your AWS account. The role is where you define what you allow a federated user to do after they sign in.
- To create an IAM role, go to the AWS IAM console. Select Roles > Create role.
- Choose the SAML 2.0 federation role type.
- For SAML Provider, select the provider which you created in Step 2.
- Choose Allow programmatic and AWS Management Console access to create a role that can be assumed programmatically and from the AWS Management Console.
- Review your SAML 2.0 trust information and then choose Next: Permissions.
- For this walkthrough, you are going to create two roles that can be assumed by SAML 2.0 federation. For GoogleSAMLPowerUserRole, you will attach the PowerUserAccess AWS managed policy. This policy provides full access to AWS services and resources, but does not allow management of users and groups. Choose Filter policies, then select AWS managed – job function from the dropdown. This will show a list of AWS managed policies designed around specific job functions.
- To attach the policy, select PowerUserAccess. Then choose Next: Tags, then Next: Review.
- Finally, choose Create role to finalize creation of your role.
Repeat steps a to g for the GoogleSAMLViewOnlyRole, attaching the ViewOnlyAccess AWS managed policy.
- Document the ARN of both roles. The ARN should be similar to
Step 4. Assign the user’s role in Google Workspace
Here you will specify the role or roles that this user can assume in AWS.
- Log in to the Google Admin console.
- From the Admin console Home page, go to Directory > Users and select Manage custom attributes from the More dropdown, and choose Add Custom Attribute.
- Configure the custom attribute as follows:
Category: AWS Description: Amazon Web Services Role Mapping
For Custom fields, enter the following values:
Name: AssumeRoleWithSaml Info type: Text Visibility: Visible to user and admin InNo. of values: Multi-value
- Choose Add. The new category should appear in the Manage user attributes page.
- Navigate to Users, and find the user you want to allow to federate into AWS. Select the user’s name to open their account page, then choose User Information.
- Select on the custom attribute you recently created, named AWS. Add two rows, each of which will include the values you recorded earlier, using the format below for each AssumeRoleWithSaml row.
The format of the AssumeRoleWithSaml is constructed by using the RoleARN(from Step 3-h) + “,”+ Identity provider ARN (from Step 2-g), this value will be passed as SAML attribute value for attribute with name https://aws.amazon.com/SAML/Attributes/Role. The final result will look similar to below:
Step 5. Set up Google Workspace as a SAML identity provider (IdP) for AWS
Now you’ll set up the SAML app in your Google Workspace account. This includes adding the SAML attributes that the AWS Management Console expects in order to allow a SAML-based authentication to take place.
Log into the Google Admin console.
- From the Admin console Home page, go to Apps > Web and mobile apps.
- Choose Add custom SAML app from the Add App dropdown.
- Enter AWS Single-Account Access for App name and upload an optional App icon to identify your SAML application, and select Continue.
- Fill in the following values:
ACS URL: https://signin.aws.amazon.com/saml Entity ID: urn:amazon:webservices Name ID format: Name ID: Basic Information > Primary email
Note: Your primary email will become your role’s AWS session name
- Choose CONTINUE.
- AWS requires the IdP to issue a SAML assertion with some mandatory attributes (known as claims). The AWS documentation explains how to configure the SAML assertion. In short, you need to create an assertion with the following:
- An attribute of name https://aws.amazon.com/SAML/Attributes/Role. This element contains one or more AttributeValue elements that list the IAM identity provider and role to which the user is mapped by your IdP. The IAM role and IAM identity provider are specified as a comma-delimited pair of ARNs in the same format as the RoleArn and PrincipalArn parameters that are passed to AssumeRoleWithSAML.
- An attribute of name https://aws.amazon.com/SAML/Attributes/RoleSessionName (again, this is just a definition of type, not an actual URL) with a string value. This is the federated user’s role session name in AWS.
- A name identifier (NameId) that is used to identify the subject of a SAML assertion.
Google Directory attributes App attributes AWS > AssumeRoleWithSaml https://aws.amazon.com/SAML/Attributes/Role Basic Information > Primary email https://aws.amazon.com/SAML/Attributes/RoleSessionName
- Choose FINISH and save the mapping.
Step 6. Test the integration between Google Workspace and AWS IAM
- Log into the Google Admin portal.
- From the Admin console Home page, go to Apps > Web and mobile apps.
- Select the Application you created in Step 5-i.
- At the top left, select TEST SAML LOGIN, then choose ALLOW ACCESS within the popup box.
- Select ON for everyone in the Service status section, and choose SAVE. This will allow every user in Google Workspace to see the new SAML custom app.
- Now navigate to Web and mobile apps and choose TEST SAML LOGIN again. Amazon Web Services should open in a separate tab and display two roles for users to choose from:
- Select the desired role and select Sign in.
- You should now be redirected to AWS Management Console home page.
- Google workspace users should now be able to access the AWS application from their workspace:
By following the steps in this blog post, you’ve configured your Google Workspace directory and AWS accounts to allow SAML-based federated sign-on for selected Google Workspace users. Using this over IAM users helps centralize identity management, making it easier to adopt a multi-account strategy.
If you have feedback about this post, submit comments in the Comments section below. If you have questions about this post, contact AWS Support.
Want more AWS Security news? Follow us on Twitter.