Instructions

NB: It is assumed that AWS Organizations and IAM Identity Center will already be set up in a separate AWS account (and potentially different region) within your AWS organization. The SAML applications will have to be created in AWS IAM Identity Center in the same account in which your AWS organization has been set up. So, before you start, ensure that you either have access to this environment or have someone with the required access assist with the creation of the SAML applications.

[.callout-primary--alert]To set up Single Sign-On (SSO) for Amazon Connect, you'll configure the SAML application in the IAM Identity Center, which is often in a separate AWS account and region. However, the Identity Provider, Role, and Policy should be established within the same AWS account as Amazon Connect.[.callout-primary--alert]

‍

Configure SSO for Amazon Connect

The following AWS guide describes in detail how to configure Amazon Connect SSO with AWS as the identity provider: https://catalog.workshops.aws/amazon-connect-sso/en-US/6-sso-amazonconnect-aws-iam-identity-center

It is recommended to use Service Control Policies (SCPs) to manage permissions regarding what users and roles can do in Amazon Connect, protecting important resources and making your system more secure.

[.callout-primary--book]Recommended reading: Security Best Practices for Amazon Connect [.callout-primary--book]

Below is an example SCP that can be used to prevent the deletion of the Amazon Connect instance and associated Role:

<pre><code class="language-json">
{    
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AmazonConnectRoleDenyDeletion",
      "Effect": "Deny",
      "Action": [
        "iam:DeleteRole"
      ],
      "Resource": [
        "arn:aws:iam::*:role/***Amazon Connect user role***"
      ]
    },
    {
      "Sid": "AmazonConnectInstanceDenyDeletion",
      "Effect": "Deny",
      "Action": [
        "connect:DeleteInstance"         
      ],
      "Resource": [
        "***Amazon Connect instance ARN***"
      ]
    }
  ]
} 
</pre></code>

Configure SSO for Local Measure Engage

Single Sign On (SSO) for Local Measure Engage is implemented by configuring the Cognito Userpool to use a SAML application for sign-in. The Cognito Userpool in question is the one which was created by the Local Measure Engage CloudFormation template.

The following summarizes the high-level process which needs to be followed:

1. Gather the required Cognito Userpool details
2. Create the SAML application in AWS IAM Identity Center
3. Configure an identity provider in the Cognito Userpool
4. Specify this identity provider to be used for agent authentication

The below will guide you through the detailed process.

‍

Step 1: Gather the required Cognito Userpool details

Log into the AWS account in which the Local Measure Engage CloudFormation stack has been created. Navigate to the Cognito service (ensure that you are in the correct region) and open the UserPool which was created when the Local Measure Engage CloudFormation stack has been created. Note down the User pool ID as per the below image.

Click on the 'App Integration' tab and note down the Cognito domain prefix. This is the first part of the Cognito domain, before the '.auth.regionxxx' as highlighted in the image below. This is also the value that was specified in the CloudFormation template so can also be copied from the CloudFormation parameters tab if preferred.

Step 2: Create the SAML application in AWS IAM Identity Center

Log into the AWS account in which AWS IAM Identity Center has been configured. Navigate to 'Application assignments -> Applications' and click on 'Add application'. Select 'Add custom SAML 2.0 application'.

In the resulting screen fill in the following:

• Display name - enter a sensible display name. This will be the name displayed on the SAML tile.
• Application start URL - this is optional and can be left empty. The Local Measure Engage url can be added here. This is the same url that has been added as an approved origin in Amazon Connect and has the following format:  https://${LMWorkspace}.${LMRegion}.localmeasure.com
  Remember to replace the placeholders in the url before adding this to the start url.
• Relay state: leave this blank
• Under Application metadata, ensure that 'Manually type your metadata values' is selected and specify the following:

• Application ACS url: https://${yourDomainPrefix}.auth.${region}.amazoncognito.com/saml2/idpresponse
• Application SAML audience: urn:amazon:cognito:sp:${yourUserPoolID}

[.callout-primary--alertmessage]NB: Ensure to replace all the above placeholders with the values copied from the Cognito Userpool.[.callout-primary--alertmessage]

Your configuration should look something like the image below:

Click 'Submit'

Click 'Actions -> Edit attribute mappings' as per the below screenshot:

‍

Ensure the following two attributes are added to the application:

 The below screenshot illustrates the configuration with the values added:

Click 'Save changes'

Under 'Assigned users' click the 'Assign Users' button and add either users or groups of users who should have access to Local Measure Engage.

Once completed, again click on 'Actions' and select 'Edit configuration'. 

Click the 'Download' button under 'IAM Identity Center SAML metadata file'. Save this file as this will be required to complete the Cognito configuration.

Step 3: Configure an identity provider in the Cognito Userpool

Log into the AWS account which contains the Cognito Userpool. Navigate to Cognito and open the Userpool.

Select the 'Sign-in experience' tab and then click on 'Add identity provider' as indicated on the below image:

On the resulting page, select 'SAML'.

Under 'Set up SAML federation with this user pool':

• Provider name - enter a name for this identity provider. It is recommended to not use any spaces in the name.
• Metadata document source - select 'Upload metadata document ->  choose file' and select the SAML metadata file downloaded from AWS IAM Identity center.

Under 'Map attributes between your SAML provider and your user pool', set the following attribute:

Click 'Add identity provider'. At this point the required identity provider has been created. The last step in the Cognito configuration is to specify that the App Client should use this identity provider. 

Step 4: Specify this identity provider to be used for agent authentication

Select 'App integration' from the tabbed view, scroll to the bottom and click on the 'app-client' to open it.  Once the app-client has been opened, scroll down to the 'Hosted UI' section and click 'Edit' as illustrated below:

Under 'Hosted sign-up and sign-in pages' scroll down to the 'Identity providers' dropdown box. Click on this and select the identity provider that was configured in the previous step. Click 'Save changes'.

Local Measure will require the name of the IDP (as configured under 'Sign-in experience') to complete the setup of your account. Please include this along with the CloudFormation outputs information shared with Local Measure.

‍