Enabling federation with AWS Single Sign-On and Amazon Connect

If you don’t have an SAML 2.0–compliant identity provider available for your contact service, it can take significant effort to set up a new one. Amazon Connect supports SAML 2.0–compliant identity providers (IdPs) for single sign-on (SSO). AWS Single Sign-On (AWS SSO) makes it easy to centrally manage SSO access to multiple AWS accounts and business applications. With AWS SSO, you can easily manage SSO access and user permissions to all of your accounts in AWS Organizations centrally.

In this post, I walk through steps to enable SAML 2.0 federation with AWS SSO and Amazon Connect. This simplifies the SSO experience with Amazon Connect.

Solution overview

Here are the steps that you follow:

Create an Amazon Connect instance with SAML 2.0-based authentication.
Create an AWS SSO application to connect to the Amazon Connect instance.
Create an IAM identity provider, IAM policy, and IAM role.
Finish configuring the AWS SSO application.
Create users and import them to Amazon Connect.
Test SSO using AWS SSO with Amazon Connect.

Prerequisites

To follow this walk-through, you should first complete the following:

Meet the AWS SSO prerequisites.
Enable AWS SSO. For more information, see How to create and manage users within AWS Single Sign-On.
Connect an AWS SSO directory. For this post, I used an AWS Managed Microsoft AD directory in us-east-1 Region (N. Virginia).
Be familiar with Amazon Connect.

For the examples in this post, I used the us-east-1 Region.

Step 1: Create an Amazon Connect instance with SAML 2.0-based authentication

In the Amazon Connect console, create a new Amazon Connect instance. For more information, see Configure SAML for Identity Management in Amazon Connect. Accept the default options, except for the following:

Admin account—Name it Connect-Admin.
Telephony options— Select both incoming and outbound calls options.

You can view or update your instance settings later.

Step 2: Create an AWS SSO application to connect to the Amazon Connect instance

In the AWS SSO console, create a new application for Amazon Connect. Accept the default values except for the following:

For Relay state, add a relay state URL:
- https://region-id.console.aws.amazon.com/connect/federate/instance-id

For this walk-through, use the Amazon Connect console as the destination. You can specify an Amazon Connect Control Panel (CCP) link for Relay state. For more information, see Use a Destination in Your Relay State URL.

The Region ID is included as part of the Amazon Connect instance ARN. For more information, see How do I find my Amazon Connect instance? Note the ARN for later.

The AWS SSO metadata is required when you create a new IAM identity provider. On the Configuration tab, under AWS SSO metadata, choose Download metadata file. Save it on your local machine.

This configuration provides AWS SSO with permissions to authenticate users from the associated directory. It provides SAML 2.0 tokens that those users can use to log in to Amazon Connect.

Step 3: Create an IAM identity provider, IAM policy, and IAM role

To federate users, you must create an IAM IdP, IAM policy, and IAM role. The IAM identity provider is used to configure AWS SSO as an IdP for SAML 2.0 federation. The IAM policy and role are used for the directory users to assume an IAM role and access an Amazon Connect instance.

In the IAM console, create a new IdP with provider type SAML. Name it Connect-SSO, or another name with a maximum of 128 alphanumeric and ‘._-‘ characters. Upload the AWS SSO application metadata.

Change to JSON view and create an IAM policy using the following policy template. Name it Connect-SSO-Policy. Replace <connect instance ARN> with your Amazon Connect instance ARN. GetFederationToken allows the federated user to retrieve a token for federation.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Action": "connect:GetFederationToken",
            "Resource": [
                "<connect instance ARN>/user/${aws:userid}"
            ]
        }
    ]
}

Next, create an IAM role for federated users so they can access the newly created Amazon Connect instance. This is the role that your users assume. For more information, see Configure SAML for Identity Management in Amazon Connect.

Accept the default values except for the following:

For SAML provider, enter Connect-SSO.
Choose Allow programmatic and AWS Management Console access.
For Policy, choose Connect-SSO-Policy.
For Name, choose Connect-SSO.

Take note of the IAM role ARN. You use it later while configuring the AWS SSO application. For example:

arn:aws:iam::<account id without hyphen>:role/Connect-SSO

Step 4: Finish configuring the AWS SSO application

Now finish configuring the AWS SSO application by mapping attribute values. Add the following attributes and values:

Attribute: Subject
- Value: ${user:email}
Attribute: https://aws.amazon.com/SAML/Attributes/RoleSessionName
- Value: ${user:email}
Attribute: https://aws.amazon.com/SAML/Attributes/Role
- Value: <IAM role ARN>,<IAM identity provider ARN>
Example value: arn:aws:iam::123456789012: role/Connect-SSO,arn:aws:iam::123456789012:saml-provider/Connect-SSO

For this post, you use the email attribute as a role session name as well as a username for Amazon Connect. The ${user:email} value in AWS SSO is mapped to ${dir:windowsUpn} in the connected directory by default. For more information, see Attribute Mappings.

Next, assign the users or groups to the application.

Step 5: Add users to Amazon Connect

After you configure the AWS SSO application, add users in Amazon Connect. Make sure to use the login name that is same as the user’s Windows user principal name. The login name is case-sensitive. For example:

First name: Connect
Last name: SSO
Login name: connect-sso@connect.local

Step 6: Test SSO using AWS SSO with Amazon Connect

This is the last step in this walk-through. You can now log in to AWS SSO and test your access to the Amazon Connect portal through SAML 2.0–based SSO. Log in with the user credentials for a user you have assigned to the Amazon Connect application in AWS SSO.

Summary

You have now successfully logged into the newly created Amazon Connect instance using AWS SSO and SAML 2.0 federation. You can start adding more users into the directory registered with AWS SSO.

With AWS SSO, there is no need to worry about maintaining Amazon EC2 instances or servers for IdPs. It is all managed by AWS. That makes it easy to onboard users to Amazon Connect.

Find more about Amazon Connect solutions in AWS Contact Center blog posts.

AWS Contact Center