Configure single sign-on using Google Workspaces for Amazon Connect

Single sign-on (SSO) is an authentication mechanism that allows users to access multiple applications securely with a single set of credentials. Users no longer need to remember multiple usernames and passwords, allowing them to maintain a singular experience for authenticating into multiple applications. Contact Centers applications are no different and require the ability to utilize single sign-on for authentication. Amazon Connect supports identity federation with Security Assertion Markup Language (SAML) 2.0 to enable web-based single sign-on from your organization to your Amazon Connect instance.

Google Workspaces is one of the common identity providers, organizations want to enable SSO with. This blog post provides a detailed guidance on how to configure SSO using Google Workspaces for Amazon Connect.

Overview of solution

In this solution, you will establish SAML 2.0 (Security Assertion Markup Language 2.0) based federation between your identity provider (IdP), Google Workspaces and AWS Identity and Access Management (IAM) for Amazon Connect. This enables your users to use single sign-on from your Google workspace organization to your Amazon Connect instance.

The preceding diagram shows the flow for SAML requests to authenticate users and federate with Amazon Connect. The description of the diagram is as follows:

The federated user clicks on the Google Workspaces SSO link to AWS in their browser. If the user has not logged in, it will go to the Google Workspaces account login portal.
The Google federation service authenticates the user credentials, and then generates a SAML authentication response to identify the user and includes custom attributes.
It posts the SAML assertion to the user’s browser.
The user’s browser posts the SAML assertion to the AWS sign in SAML endpoint (https://signin.thinkwithwp.com/saml). AWS sign in receives the SAML request, processes the request, authenticates the user, and forwards the authentication token to Amazon Connect.
Using the authentication token from AWS, Amazon Connect authorizes the user and opens Amazon Connect in their browser.

Walkthrough

During the setup, you will perform the following high-level steps.

Create an Amazon Connect instance and choose SAML 2.0-based authentication for identity management.
Get SAML metadata from Google Workspaces
Create an IdP in AWS
Create an IAM role in AWS
Create a custom user attribute in Google Workspaces
Add the AWS SAML attributes to your Google Workspaces user profile
Setup AWS SAML App in Google Workspaces and provide Amazon Connect instance starting URL
Grant access to users in Google Workspaces
Test federated access to Amazon Connect instance
Add users in Amazon Connect Instance (agents)

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

Prerequisites

For this walkthrough, you should have the following prerequisites:

An AWS account
Basic understanding of Amazon Connect and privileges required to create an Amazon Connect instance
Basic understanding of IAM and privileges required to create the following; IAM identity provider, roles, policies, and users
A Google Workspaces account
An existing user defined in Google Workspaces to be used as the Amazon Connect Administrator

1. Create an Amazon Connect Instance configured for SAML 2.0

In Amazon Connect, you can define the identity management for your Amazon Connect users at instance creation. You cannot change the option you select for identity management after you create the instance. For the purpose of this blog post, you will create a new Amazon Connect instance, choose SAML 2.0 based authentication to federate it with Google Workspaces.

For configuring Amazon Connect instance, navigate to Getting Started with Amazon Connect section of the Amazon Connect Administrator Guide.

Follow the steps at Create an Amazon Connect instance and note the following

i. On Step 1: Identity management, select SAML 2.0-based authentication

ii. On step 2, for Administrator enter the First Name, Last Name, and Username of an existing Google Workspaces user.

Note: It is critical that the Username entered in Amazon Connect matches the user name in Google Workspaces exactly.

iii. For the purpose of this demo, we are keeping defaults for step 3, Telephone Options and step 4, Data Storage. On step 5, Review and Create the Amazon Connect instance.

iv. Your Amazon Connect instance is created.

v. Click on the Amazon Connect instance alias, and note down the instance-id.

Note: The instance ID is the set of numbers and letters after ‘/instance’ in the Instance ARN displayed on the Overview page. For example, the instance ID in the following Instance ARN is 178c75e4-b3de-4839-a6aa-e321ab3f3770.

arn:aws:connect:us-east-1:450725743157:instance/178c75e4-b3de-4839-a6aa-e321ab3f3770

Now let’s continue on enabling federation with Google Workspaces.

2. Get SAML metadata from Google Workspaces

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.

i. Log in to your Google Admin console with admin credentials.

ii. Go to Set up single sign-on (SSO) for SAML applications

iii. Click Download Metadata in IdP metadata section to download the IdP metadata XML file. This is the format we need for the AWS IdP configuration.

3. Create IdP in your AWS account

Now, let’s create a SAML 2.0 identity provider in IAM to establish trust between your Google Workspaces SAML-compatible IdP and AWS. IAM SAML identity providers are used as principals in an IAM trust policy.

i. Login to the AWS Management Console and choose IAM.

ii. In the navigation pane, choose Identity Providers.

iii. Choose Add provider.

iv. Choose SAML, and provide a name for the provider and then browse to the IdP metadata XML document downloaded earlier in Step 2 for Metadata Document.

v. Click on Add provider. Your newly created IdP will appear in the list on Identity Providers page.

vi. Click on your newly created IdP and note down the ARN for your IdP. We would use this ARN later. It would be in the form of

arn:aws:iam::<YOURACCOUNTNUMBER>:saml-provider/Googleworkspacesdemo

4. Create an IAM Role in your AWS Account

Now, let’s create an IAM Role. It will determine what permissions the users who log in (through your identity provider) will have in AWS. In this case, the permissions are for accessing the Amazon Connect instance. You can control the granular permissions users can have within your contact center by using the security profiles in Amazon Connect.

i. In the IAM console, choose Roles from the navigation pane.

ii. Choose Create Role.

iii. Select SAML 2.0 federation as a type of trusted entity, choose the IdP provider you created in Step 3

iv. Select Allow programmatic and AWS Management Console access, and click on Next: Permissions.

v. On the Attach permissions policy page, choose Create policy. This would open Create Policy page in another browser tab.

vi. On the Create policy page, choose JSON.

vii. Copy the following policy and paste it into the JSON policy editor, replacing any existing text (as shown following screenshot).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement2",
            "Effect": "Allow",
            "Action": "connect:GetFederationToken",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "connect:InstanceId": "<instance-ID>"
                }
            }
        }
    ]
}

viii. Replace the value for the connect:InstanceId to the instance ID for your Amazon Connect instance, noted down in Step 1. Click on Next: Tags.

This policy only allows the user to get a federation token to a specific Amazon Connect instance. You can customize the policy for your specific requirements. Additional examples are provided at Configuring SAML with IAM for Amazon Connect.

ix. Optionally add tags. Click on Next: Review. Provide a Policy Name and add Description (optional).

x. Click on Create Policy. The policy gets created and is available in the list of policies (as show in following screenshot). You can now use this policy in your role.

xi. Navigate back to Create Role browser tab. On the Attach Permission Policies page, search for the policy you created in previous step and select it. Click on Next: Tags and optionally add tags.

Note: If the policy doesn’t show up initially as you search. Click on the refresh button.

xii. Click on Next: Review. Provide a Role name and description (optional).

xiii. Click on Create Role.

xiv. Click on your newly created Role and note down the ARN for it. We would use this ARN later. It would be in the form of

arn:aws:iam::<YOURACCOUNTNUMBER>:role/Googleworkspacesdemorole

5. Create a custom user attribute in Google Workspaces

Now let’s create a custom user attribute in your Google Workspaces. This will allow us to add the SAML attributes that the AWS Management Console expects in order to allow a SAML-based authentication.

i. Log in to your Google Admin console with admin credentials, and navigate to Users.

ii. At the top of Users list, click Manage custom attributes.

iii. At the top right, click Add Custom Attribute.

iv. Configure the custom attribute as follows:

- Category: Amazon
- Description: Amazon Custom Attributes

For Custom fields, enter the following:

- Name: Role
- Info type: Text
- Visibility: Visible to user and admin
- No. of values: Multi-value

v. Click Add. The new category appears in the Manage user attributes page

6. Add the AWS SAML attributes to your Google Workspaces user profile

Once we have configured a custom user attribute, let us add the SAML attributes that we noted earlier, to the Google workspaces user profile.

i. While logged in to your Google Admin console with admin credentials, navigate to Users.

ii. In the Users list, find the user. If you need help, see Find a user account.

Note: Select the user that has the exact same username which you used while you were creating Amazon Connect instance Administrator in step 1.

iii. Click the user’s name to open their account page.

iv. Click User information.

v. Click on the custom attribute you recently created, named Amazon.

vi. Add a value to this custom attribute noted earlier in step 3 and 4 in the following manner (as shown in screen shot)

<AWS Role ARN>,<AWS provider/IdP ARN>

vii. Click Save.

7. Setup AWS SAML app in Google Workspaces and provide Amazon Connect instance starting URL

Now you have everything in place, and you are ready to create your SAML app within your Google Workspaces account. It will provide the entry point for your Google Workspace users to SSO into the Amazon Connect instance.

i. While logged in to your Google Admin console with admin credentials, navigate to Apps > Web and mobile apps.

ii. Click on Add App in the top, and Search for apps. Enter Amazon Web Services in the search field.

iii. In the search results, hover over the Amazon Web Services SAML app and click Select.

iv. On the Google Identity Provider details page, click Continue.

v. On the Service provider details page, the ACS URL and Entity ID values for Amazon Web Services are configured by default.

- Configure the Start URL identity provider to point to your Amazon Connect instance. The URL to use for it is comprised as follows:

https://region.console.thinkwithwp.com/connect/federate/instance-id

- Replace the region with the Region name where you created your Amazon Connect instance, such as (in example of this demo) us-west-2 for US West (Oregon). Replace the instance-id with the instance ID for your instance, noted down in step 1 (as shown in screen shot).

vi. On the Attribute Mapping page, click the Select field menu and map the following Google directory attributes to their corresponding Amazon Web Services attributes:

Google directory attribute	Amazon Web Services attribute
Basic Information > Primary Email	https://thinkwithwp.com/SAML/Attributes/RoleSessionName
Amazon > Role	https://thinkwithwp.com/SAML/Attributes/Role

Note: It is critical that the Basic Information > Primary Email here exactly matches the Amazon Connect user name.

vii. Click Finish.

8. Grant access to users in Google Workspaces

When you create a SAML app, it is turned off by default. This means for users logged in to their Google Workspaces account, the SAML app will not be visible to them. You will now enable the AWS SAML app to your Google Workspaces users.

i. While logged in to your Google Admin console with admin credentials, navigate to Apps > Web and mobile apps.

ii. Select Amazon Web Services app

iii. Click User access.

iv. To turn on a service for everyone in your organization, click ON for everyone, and then click Save.

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

For example, let’s say you have two simple organizations within a parent organization of Admin users: – General user and Amazon Connect user (you can refer to the Google documentation for further details about creating these organizations). You want to configure access rights so that only users from the Amazon Connect user’s organization will have access to this SAML app. The steps below explain on how to do it:

- At the left, select the organization unit Amazon Connect users.
- Select On or Off.
- Click Override to keep your setting if the service for the parent organizational unit is changed.

If Overridden is already set for the organizational unit, choose an option:

Inherit – Reverts to the same setting as its parent.

Save – Saves your new setting (even if the parent setting changes).

Now, any user part of this organization who logs in to their Google Workspaces account will see the new application- Amazon Web Services SSO application.

In this case, the newly created application is represented by an orange cube with the label Amazon Web Services, as shown in the following screenshot.

9. Verify federated access to your Amazon Connect instance

You are now ready to test SAML 2.0 based authentication with Amazon Connect for users in your existing identity provider, Google Workspaces.

i. Open a new browser session, for example, using Chrome, open a new incognito window.

ii. Login into your Google Workspaces account (for the purpose of this demo, we have been using Google Workspaces admin account)

iii. Click on the Amazon Web services application in your Google apps.

Clicking this AWS application will now handle all of the SAML-federated SSO for your Google Workspaces account and log you to the Amazon Connect instance as the Administrator.

At the top right, you will see the username with which it is currently federated with. The username is the same which we chose as an administrator for Amazon Connect instance in Step 1.

You have successfully configured Google Workspaces SSO for Amazon Connect instance for your administrator.

10. Add additional users to Amazon Connect instance

In Amazon Connect instance , you can add additional users with different security profiles. While adding users to your Amazon Connect instance, make sure that the user names (email) match exactly with the email IDs in your existing Google Workspaces account.

Note: If the user names do not match, users can log in to the identity provider, but will not be able to access Amazon Connect. This is because their user name doesn’t exist in Amazon Connect

Administrators of Amazon Connect instance can add users manually on the User management page.

i. While logged in as your Amazon Connect administrator , navigate to the User management page

ii. Click on Add new users

iii. Add in user details, making sure username matches to your user’s email ID in Google Workspaces account.

iv. In the Security Profile, choose Agent and Add the new user.

Note: You can also bulk upload users with a CSV template. For more information, navigate to Add users to your Amazon Connect instance.

v. Add custom SAML user attributes to its Google workspaces user profile, similar to admin user in Step 6.

Note: You need to add custom SAML user attributes as described in Step 6, for every new user in Google workspace. For managing bulk changes to Google workspaces user profile attributes, see Sending Batch Requests.

vi. Log in to the currently created user’s Google Workspace account, and click on the Amazon Web services application in your Google apps.

vii. It should open up the Amazon connect contact control panel (CCP)

You have successfully configured Google Workspaces SSO for Amazon Connect instance for agents, based on the security profile chosen earlier.

Cleaning up

You can delete the Amazon Connect instance and other resources created. Navigate to Delete your instance section of Set up your contact center.

Conclusion

In this post, you have established SAML based federation using, Google Workspaces for your Amazon Connect instance. For more information regarding Amazon Connect users, see the Amazon Connect Administration Guide.

Jamal Arif is a Solution Architect at Amazon Web Services, where he helps customers build innovative, resilient and cost-effective solutions using AWS services. In his spare time, Jamal enjoys spending time outdoors with his family hiking and mountain biking.

AWS Contact Center