Configure single sign-on using Microsoft Azure Active Directory for Amazon Connect

Join us for AWS Contact Center Day, a free virtual event where you’ll learn about the future of customer service, how machine learning can optimize customer and agent experiences—and more. Register now »

Single sign-on (SSO) enables users to access multiple applications securely via a single ID and password. This reduces the headache of remembering multiple username and passwords for users in an organization. Contact Centers are no different and the ability to utilize SSO for contact center applications is a common requirement. Amazon Connect supports identity federation with Security Assertion Markup Language (SAML) 2.0 to enable web-based single sign-on (SSO) from your organization to your Amazon Connect instance.

One of the common identity providers most organizations want to use to enable SSO with AWS is Microsoft Azure Active Directory (Azure AD). This post provides a detailed guidance on how to enable SSO using Azure AD for Amazon Connect.

Overview of solution

The following architecture diagram depicts two Azure AD AWS Enterprise Applications that federate via Identity Provider initiated SSO to AWS Identity and Access Management (IAM). This helps grant access to your Amazon Connect Instance. The first application is created for Administrators of your contact center. The second application is created for agents.

Walkthrough

The high-level steps that we will walk through in this post are as follows:

Create IAM policies to enable federation of Azure AD to access AWS resources
Create an IAM user with AWS Command Line Interface (CLI) access and apply IAM policies
Download IAM user credentials for Azure AD provisioning access
From Azure AD create an AWS SAML Enterprise application and the download the ‘Federation Metadata XML’. This application will be your Azure AD application for Administrators
Create an IAM identity provider, a role, apply policies, and upload the federation metadata XML
Within Azure AD enter your IAM user credentials, enable Provisioning, and test the AWS SAML application
Within Azure AD assign your Amazon Connect administrator to the Azure AD SAML application and assign appropriate role
Test the application
Add administrator users to Amazon Connect and to Azure AD
Repeat similar steps to add a second Azure AD application for your agents

At the end of this blog post, you will have created two applications that will enable your administrators and agents to log into Amazon Connect using Azure AD SSO

Prerequisites

For this walkthrough, it is assumed you have the following prerequisites:

An AWS account
An Amazon Connect instance with SAML 2.0 as the chosen Identity Provider
Basic understanding of Amazon Connect
Basic understanding of IAM and privileges required to create the following; IAM identity provider, roles, policies, and users
An Azure AD subscription
A user created in Azure AD that will act as your Amazon Connect administrator
An administrator user defined in Amazon Connect with the name exactly matching its counterpart in Azure AD ( as mentioned in the above step)

Create the IAM policies

There are two required policies that need to be created. The first policy enables federation for all users in a specific Amazon Connect instance. The second policy allows Azure AD to list IAM roles and account aliases.

To create the Amazon Connect federation IAM policy:

Login to the AWS Management Console and choose IAM
In the navigation pane, choose Policies
Choose Create policy
Select the JSON tab

Paste the following policy into the editor, replacing the existing content:

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

Replace **YOUR ARN** with the ARN for your instance. To find your ARN:
1. Open a new browser tab and log into your Amazon Connect Console
2. Choose your Instance Alias
3. Copy value of your Instance ARN
Paste the value of the Instance ARN and choose Review Policy
Name your policy ‘azure_federation_policy’, or something similar
Optionally, provide a description for the policy
Choose Create policy

To create the Azure AD access IAM policy:

In the IAM console, choose Policies again
Choose Create policy
Select the JSON tab

Paste the following policy into the editor, replacing the existing content:

{
    "Version": "2012-10-17",
    "Statement": [
        {
          "Effect": "Allow",
          "Action": [
              "iam:ListRoles",
              "iam:ListAccountAliases"
          ],
          "Resource": "*"
        }
    ]
}

Verify the replacement and choose Review Policy
Name the policy ‘azure_cli_policy’, or something similar
Optionally, provide a description for the policy
Choose Create policy

Create an IAM user

An IAM user is created to allow programmatic access to AWS resources. This will allow Azure AD to retrieve the appropriate IAM credentials from your AWS account.

Login to the AWS Management Console and choose IAM
In the navigation pane, choose Users
Choose Add user
In the Set user details section, provide a Username, for example ‘azure_cli_user’
In the Select AWS access type section, choose Programmatic access
Choose Next: Permissions
In the Set permissions section, choose Attach existing policies directly
In the search field, type azure. Note: Available policies will filter.
Choose the ‘azure_cli_policy’ that you created previously
Choose Next: Tags
Optionally add tags, then choose Next: Review
Choose Create user
On the success page, download the credentials.csv file that contains your user credentials. Note: You will need this later during the Azure AD application setup.

Create the Azure AD AWS SAML application

The Azure AD AWS SAML application along with an AWS IAM identity provider will enable the federation between Azure AD and your AWS IAM users. As a part of this blog post you will end up creating two Azure AD applications- one for your Amazon Connect administrators and another for your Amazon Connect agents. At this moment we will begin by creating an application for your administrators.

Log in to the Azure AD portal with your Azure AD subscription.
On the navigation pane, select the Azure Active Directory service
Navigate to Enterprise Applications and then select All Applications
To add a new application, select New application
In the Add from the gallery section, type Amazon Web Services (AWS) in the search box
Select Amazon Web Services (AWS) from results panel and then add the application. Wait a few seconds while the application is added to your tenant.
Once the application is created, select Set up single sign on in Getting Started
Select SAML as in single sign-on method
When prompted with the Save single sign-on setting, select Yes
Edit Basic SAML Configuration to configure the Relay State URL

When configuring relay state, you can use the destination argument in the URL to navigate users directly to specific pages within your Amazon Connect instance. However, users must be assigned an Amazon Connect security profile that grants access to the page the relay state is configured for. You must use URL encoding for the destination value used in the Relay state URL. The following are relay state examples you will use for this article:

Amazon Connect administrators relay state URL to launch the Amazon Connect Console:

https://<regionid>.console.aws.amazon.com/connect/federate/<instance-id>?destination=%2Fconnect%2F

Note: The %2F encoding equates to a ‘/’. This is not required but is best practice. Depending on your environment, you may need the ‘/’ for the URL to resolve. You can also append the URL to direct the user to additional points within the Amazon Connect console.

Amazon Connect agents relay state URL to launch the Contact Control Panel(CCP):

https://<regionid>.console.aws.amazon.com/connect/federate/<instance-id>?destination=%2Fconnect%2Fccp

For the current Azure AD application, use the relay state URL for Amazon Connect administrators as highlighted above.
1. Replace the <region-id> with the Region name where you created your Amazon Connect instance. For example ‘us-east-1’ for US East (N. Virginia).
2. Replace the <instance-id> with the instance ID for your instance.
  To find your instance ID:
  1. Open a new browser tab and go to the Amazon Connect Console
  2. Choose your Instance Alias
  3. The instance ID is everything after the last forward slash ‘/’ in the Instance ARN.
    For example, in bold:
    arn:aws:connect:us-east-1:123456789:instance/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
3. Enter your Relay State URL for your specific instance in the Basic SAML Configuration and select Save
4. Verify the Relay State URL, ensure there are no spaces or missing characters
From the Set up single sign-on with SAML go to SAML Signing Certificate section and Download the Federation Metadata XML. This will download the certificate locally on your computer.

Do not close out of the Azure AD Portal as you will need to continue the setup shortly.

Create an IAM identity provider

Now that you have created the Azure AD application and downloaded the federation metadata XML, you will create an IAM identity provider in AWS Management Console and upload this metadata file.

Login to the AWS Management Console and choose IAM
In the navigation pane, choose Identity Providers
Choose Create provider
Choose SAML as the Provider Type
For Provider Name, enter ‘AzureAD_Connect_Admin’
In the Metadata Document section, choose the metadata.xml document you downloaded in a previous step
Choose Next Step
Validate the Provider information and choose Create

Create an IAM role

Now create an IAM role to access the IAM identity provider you configured in the previous step

In the IAM console, from the navigation pane, choose Roles
Choose Create role
Choose SAML 2.0 federation
In the SAML provider section, choose ‘AzureAD_Connect_Admin’
Choose Allow programmatic and AWS Management Console access
Choose Next: Permissions
In Filter policies, type ‘azure’
Select both policies you created earlier
Choose Next: Tags
Choose Next: Review
For Role name, enter a unique name, for example ‘AzureAD_Role’
Choose Create Role

Configure Azure AD AWS SAML application with the IAM identity provider

Once you have created an IAM identity provider, you will continue to finish the Azure AD application setup.

Return to the Azure portal
Navigate to Enterprise Applications and select your Amazon Web Services app
Select Provisioning on the left and select Get started
In the Provisioning Mode drop down, change from Manual to Automatic
Open the credentials csv file you downloaded from the IAM user setup
Copy the Access key ID from the file and past into the clientsecret in Admin Credentials
Copy the Secret access key and past into the Secret Token in Admin Credentials
Click Test Connection, you should receive a browser notification with a successful test message
Select Save
After saving, switch Provisioning Status to On and Save again

Assign user to the Azure AD AWS SAML application

Now you can assign your Amazon Connect administrator as a user to your new Azure AD Amazon Web Services SAML Application.

In the Azure portal, navigate to your Amazon Web Services application
Go to Users and groups and select Add user
Select the Azure AD user you used as an administrator for your Amazon Connect instance, from Users and choose Select
Select the roles from Select Role and choose Select

Note: If you do not yet see the role populate, the handshake between Azure AD and AWS IAM may still be taking place. This process can take anywhere from a few minutes to several hours depending on your environment.
Select Assign
Confirm your user was added

Test your new Azure AD AWS SAML application

Once you have completed the Azure AD application setup you can test your application via the application URL.

Go to Properties and copy the User access URL
Open a new browser session. For example, using Chrome, open a new Incognito window
Paste the URL link into your new browser session
Login to your Azure AD application using the credentials of the user you assigned as the Amazon Connect administrator
You have now successfully logged into Amazon Connect console as an administrator for your instance

Set Up Azure AD Single Sign on for Amazon Connect Agents

Once you have successfully configured an application and SSO federation for your Amazon Connect administrators using Azure AD, you can repeat similar steps to create a new Azure AD application for your contact center agents. Please note most of the steps will remain the same as we went through for administrators with a change in Relay state URL, change in names of IAM user, identity provider and role.

Create a second Azure AD AWS SAML application for Amazon Connect agents

Sign in to the Azure portal
Follow the steps given in section ‘Create the Azure AD AWS SAML application’ with the following adjustments:
- Give the new application a unique name, for example ‘Amazon Connect Agents’
- When prompted to Save single sign-on setting, select No, I’ll save for later
- In SAML configuration Identifier (Entity ID) add a # and a unique numeric value. For example, #2 for your second app, #3 for your third, and so on….
- Configure the Relay State URL, using the agent relay state example provided earlier:
https://<regionid>.console.aws.amazon.com/connect/federate/<instanceid>?destination=%2Fconnect%2Fccp
Select Save and confirm configuration
Download the Federation Metadata XML

Configure a second IAM user, identity provider, and role

Now you will configure a second IAM user, identity provider, and role for agents. You will use the same IAM policies you created for administrator application.

To create a second IAM user:

Follow the steps outlined in the section ‘Create an IAM user’ with the following edits:

In the Set user details section, provide a unique user name, for example ‘azure_cli_agent_user’
Be sure to download the credentials.csv after creating the IAM user. Note that the credentials.csv file is for your second user.

To create a second IAM identity provider:

Follow the steps outlined in the section ‘Create the IAM identity provider’ with the following edits:

For Provider Name, enter a unique name, for example ‘AzureAD_Connect_Agent’
In the Metadata Document section, choose the metadata.xml document you save previously for the second Azure AD application

To create a second IAM role:

Follow the steps outlined in the section ‘Create an IAM role’ with the following edits:

In the SAML provider section, choose ‘AzureAD_Connect_Agent’ or the unique name you gave to your second identity provider
For Policies, select both policies you created earlier for the first Azure AD application
For Role name, enter a unique name, for example ‘AzureAD_Agent_Role’

Finish the application setup for the second Azure AD application

Follow the same steps outlined in section ‘Configure Azure AD AWS SAML application with IAM identity provider’ but use the second credentials.csv file you downloaded in the ‘To create a second IAM user’ section for agents

Add a user to your second Azure AD AWS SAML application

Now you can assign your agent as a user to your second Azure AD application.

Create a new Azure AD user or use an existing one to add to your application
Note: You cannot use the same users from your previous Azure AD applications for your new application, including your administrator. If needed, create a new user in Azure AD for your agent or select an existing user not assigned in a previous application.
Add the user to your new Azure AD application and select Role.
You will see multiple Roles appear in the drop down. Select thegent role you created.
Create the same user in Amazon Connect and set the Security Profile to Agent
Test the application using the same steps outlined in ‘Test your new Azure AD AWS SAML application’
Note: When you log in as the agent, the Amazon Connect Contact Control Panel (CCP) will launch directly.
You have now successfully configured Azure AD SSO for Amazon Connect for agents.

Additional troubleshooting tips

Trace your SAML path by utilizing the SAML-tracer Chrome extension. Open SAML-tracer in another Chrome browser tab prior to authentication and leave open during the log in attempt. The tool will capture a trace that can then help pinpoint where the issue is with the federation.
If you receive the following error message, try deleting and recreating your user in Amazon Connect as sometimes the user federation token does not refresh correctly.
If you get directed to a role selection screen and see an error at the top similar to the following, you may need to change the RoleSessionName attribute:
- RoleSessionName in AuthnResponse must match [a-zA-Z_0-9+=,.@-]{2,64} (Service: AWSSecurityTokenService; Status Code: 400; Error Code: InvalidIdentityToken……
- Try changing your RoleSessionName from user.userprincipalname to user.mail
  1. From Azure AD, go to your application Single sign-on settings and Edit the User Attributes and Claims
  2. Select the RoleSessionName
  3. Change the Source attribute to user.mail and save
  4. Test your application again

Conclusion

In this post you have learnt how to set up single sign on using Azure AD for Amazon Connect for both your contact center administrators and agents. If you have additional user types that access other areas of the console directly, you may consider building additional Azure AD applications. For example, an application for contact center managers accessing Metrics and Quality, allowing them to launch directly into specific metric reports at sign on. For more information regarding Amazon Connect users, see the Amazon Connect Administration Guide.

Amazon Connect administrators relay state URL to launch the Amazon Connect Console:

Amazon Connect agents relay state URL to launch the Contact Control Panel(CCP):

AWS Contact Center