WEB API AWS Connect application provides an integration of a Single Sign-On (SSO) enabled user interface (UI) for the AWS Connect PaaS service. It delivers an end-to-end solution for identifying authenticated callers with the Identity provider and personalizing the web chat or call experience via a single-page application (SPA) interface that contains the AWS Connect chat widget Javascript (JS) code. 

Features

Unlicensed version

• SPA for AWS Connect SSO Integration

• AWS Connect JSON Web Tokens (JWT) security support

• EntraID (Former AzureAD) support for user authentication and authorization 

• AWS Connect JWT enrichment with SSO user attributes for routing based on the authenticated user's context

• Multi-factor authentication

• Unrestricted API interface for multiple users.

Licensed version (additional features)

• Supports adding customised SSO attributes into JWT

• AWS Connect JWT SSO user attributes masking with "NoLicenseAttributesTennantID" removed

• Free version notes are removed

Architectural Components

Deployment Package. Consists of a deployment for a WEB API service, which is the package built with the .NET 7 Core Framework as a portable framework-dependent runtime that can be hosted on Azure Web Services. And a deployment for a single-page application (SPA), which can be hosted on any service that can host static HTML and JS files.

User Agent. Use a JavaScript single-page application with Microsft Authentication Library (MSAL v2). This page will host the Amazon Connect chat widget (used to initiate a chat from within the page) plus the setup of the OIDC flow to acquire OAuth2 access tokens to act on behalf of the end-user when calling WEB API service.

The JWT Compiler service. It will run as a separate WEB API service. Allows access only to the authorized scope for the user's SSO session. Microsoft Web API service provides an API controller authorization using the Microsoft Identity Web library.

EntraID (Former AzureAd) Identity provider. The service will be used for the OIDC authorization as the access token issuer for the user's approval to call the WEB API service.

Amazon Connect. The Amazon Connect PaaS service includes the contact centre backend for the chat widget, and service flows to route incoming messages and calls.

Communication between different services is as follows:

Flow steps elaborate on the above diagram.

1. Customer opens single page app (SPA) with a modern browser.

2. On startup, SPA loads the MSAL library to protect page content with OIDC SSO authentication and authorization flows and ensures the approved users can access the app.

3. The Identity Service will immediately return the SPA and JWT Compiler Function access tokens if the user is logged into any other SSO app. Otherwise, the identity service will ask the user to authenticate with SSO credentials.

4. The SPA continues the fetch process, presenting the access token to the WEB API AWSConnectJWT Function endpoint.

5. The AWSConnectJWT Function verifies the access token and extracts the subject information to build an Amazon Connect-compliant contact JSON web token (JWT), which is encoded with SSO user attributes, a security key, widget ID and expiration time (10min)

6. SPA returns the JWT to the AWS chat widget and provides the customer display name from the SSO session.

7. The chat widget initiates the chat session with Amazon Connect, including the contact JWT and the customer's display name. This will allow Amazon Connect to identify and assign clients to the correct chat queue and apply correct routing based on the user's context.

Deploy WEB API AWS Connect Service with SPA

The below steps will walk through the minimal deployment steps to start service, as explained in the architecture section.

Prerequisites

To start deployment steps successfully, you must :

• Get App Configuration Store read-only key and service endpoint configured as per https://www.securemfa.com/knowledge-base/azure-app-configuration-for-securemfa-apps  article. 

• Get App Client IDs for SPA and API applications which you will use in your environment and AzureTennantID information where applications have been registered as per https://www.securemfa.com/knowledge-base/microsoft-entraid-apps-for-spa-and-web-api  article.

• [Optional]  Install Node.js runtime environment that you can use to run SPA on a local computer written in JavaScript using http://localhost:3000  URL. The SPA can be hosted on Windows' native IIS service, too.

• [Optional] The latest Powershell modules (Az.Websites) are installed on a computer for command lines. The same actions can be completed via an Azure Portal, too.

Deploy WEB API AWS Connect Service

Preparation 

Download the smfa_webapi_awsconnect.zip compressed package on your computer.

Invoke-WebRequest -Uri "https://github.com/SecureMFA/web-api-aws-connect/blob/main/smfa_webapi_awsconnect.zip?raw=true" -OutFile ".\smfa_webapi_awsconnect.zip"

Create packagename.txt for running  WEBSITE_RUN_FROM_PACKAGE using. Azure App Service Plan.

New-Item ".\packagename.txt" -ItemType File -Value "smfa_webapi_awsconnect.zip"

Download and extract the SPA (spa-aws-connect) compressed package from GitHub on your computer.

Invoke-WebRequest 'https://github.com/SecureMFA/spa-aws-connect/archive/refs/heads/main.zip' -OutFile .\spa-aws-connect.zip

Expand-Archive .\spa-aws-connect.zip .\

Rename-Item .\spa-aws-connect-main .\spa-aws-connect ; Remove-Item .\spa-aws-connect.zip

Download Node.js dependencies to run SPA on the local computer and start SPA on http://localhost:3000 

cd "spa-aws-connect"

npm install

npm start

Create AppServicePlan and web app to host WEB API service in Azure. Record WEB_API_Endpoint for SPA configuration

$AzResourceGroup = "azsu-sMFA-WebAPI";

$AzResourceLocation = "uksouth";

$AzAppPlanName = "My-App-Service-Plan";

$RandomString = -join ((48..57) + (97..122) | Get-Random -Count 12 | % {[char]$_});

$AzWebAppName = "sMFAWEBAPI" + $RandomString;

$AzWebAppSettings=@{"WEBSITE_RUN_FROM_PACKAGE"="1";};

New-AzAppServicePlan -ResourceGroupName $AzResourceGroup -Name $AzAppPlanName -Location $AzResourceLocation -Tier "Free" -NumberofWorkers 1 | Out-Null;

New-AzWebApp -ResourceGroupName $AzResourceGroup -Name $AzWebAppName -Location $AzResourceLocation -AppServicePlan $AzAppPlanName | Out-Null;

Set-AzWebApp -AppSettings $AzWebAppSettings -Name $AzWebAppName -ResourceGroupName $AzResourceGroup | Out-Null;

write-host "WEB_API_Endpoint=" (get-AzWebApp -Name $AzWebAppName).DefaultHostName -ForegroundColor Green;

Configuration

SPA package: You MUST replace the placeholder values directly in  the authConfig.js file  with your environment's details 

msalConfig section:

clientId: 'Enter_the_Azure_WEB_MSAL_SPA_App_Id_Here', // This is mandatory field that you need to supply.

authority: 'https://login.microsoftonline.com/Enter_the_Azure_Tenant_Id_Here', // Replace the placeholder with your tenant name

redirectUri: 'http://localhost:3000', // You must register this URI on Azure Portal/App Registration. 

fqdnWebAPI section:

endpoint: 'https://Enter_the_WEB_API_Endpoint_Here/api/AWSConnectJWT'

read: ['api://Enter_the_Azure_WEB_MSAL_API_App_Id_Here/JWT.Read']

write: ['api://Enter_the_Azure_WEB_MSAL_API_App_Id_Here/JWT.ReadWrite']

WEV API smfa_webapi.zip compressed package: You MUST replace the placeholder values for the appsettings.json in the zip archive file 

ConnectionStrings section:

"AppConfigReadOnlyKey": "Endpoint=https://my-configuration-store.azconfig.io;Id=Q+va;Secret=9F4D1kxYMFOvU45n+4i78OibXdI94DfpFLrmpYRgq+s=",

"AppConfig": "https://my-configuration-store.azconfig.io"

AzureAd section:

"TenantId": "Enter_the_Azure_Tenant_Id_Here",

"ClientId": "Enter_the_Azure_WEB_MSAL_API_App_Id_Here"

AWS Connect Widget Configuration

You MUST replace the placeholder values with your details in the ui.js file (SPA package), which you must copy from your AWS Connect widget configuration and save the changes.

# ----------- Replace the AWS widget script only below --------- Do not include <script type="text/javascript"> &  </script> values

    (function(w, d, x, id){

    s=d.createElement('script');

    s.src='https://d2zasqxhmd6ne4.cloudfront.net/amazon-connect-chat-interface-client.js';

    s.async=1;

    s.id=id;

    d.getElementsByTagName('head')[0].appendChild(s);

    w[x] =  w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };

    })(window, document, 'amazon_connect', '16ac5395-77ac-4b36-bca3-c56ec92993e7');

    amazon_connect('styles', { iconType: 'CHAT', openChat: { color: '#ffffff', backgroundColor: '#123456' }, closeChat: { color: '#ffffff', backgroundColor: '#123456'} });

    amazon_connect('snippetId', 'QVFJREFIajB2ZWh0V0phclVpYUZ6M3pLNlhsbzI5ZENWTXp0dUl0L20zMmpCN0ltRGdHL0VXN2t1Wk9OellRVnFEOHc2d3liQUFBQWJqQnNCZ2txaGtpRzl3MEJCd2FnWHpCZEFnRUFNRmdHQ1NxR1NJYjNEUUVIQVRBZUJnbGdoa2dCWlFNRUFTNHdFUVFNMUFocjN4WTE1Vm1HVVJhYUFnRVFnQ3VVWUh2cVNCTHprR0FSVmJpVWJYWGFjT1NoZmk0RnJjQ1l1NUdjOTFnT0ZUQ2pURkZsSWYrWEZqNlY6OjNmR3kzNUhMMVRETTdTNThrKzZqNjNzWitJa1l6Z1hxMGlGOHBsUVR1YnozNlg2NlczaFY5ZG5FalpCN3QvcENCRHFUK2UyY2QrV2xEdTdBc0pWc1pnRjBEZktxbndZZUw2d252eGxMcjR1QlJkVWdpV3h5Z1lmNCtabVdWSXdwTkZkOXlPR0NaUlFjTTdHQmxWTWU3TnR3amNDUlc4UT0=');

    amazon_connect('supportedMessagingContentTypes', [ 'text/plain', 'text/markdown' ]);

## ----------- Replace the AWS widget script only above --------- Do not include <script type="text/javascript"> &  </script> values

Important: Update the App Configuration store  with your environment's Chat WidgetKeyId and WidgetPrivateKey

sMFA:WEBAPI:Settings:AWSConnectWidgetKeyId 

sMFA:WEBAPI:Settings:AWSConnectWidgetPrivateKey

Final Steps

You can upload smfa_webapi_awsconnect.zip and packagename.txt into C:\home\data\SitePackages Web App root location via Kudo interface or using PowerShell Commands

Confirmation

If all Deployment steps above is completed sucesfully, you should see the WEB API interface up and runningd

When loading the SPA page, you can initiate the AWS Connect chat with the user's SSO context. 

Adding SSO Custom Attributes into JWT

Licensed adapters support adding custom attributes that can be retrieved from the user's access token and passed to the AWS Connect system's backend to customise chat or call flows.  To enable custom SSO attributes, you must create the WEB API application's new setting, "sso_custom_attributes", and use a list of comma-separated attributes as a value "companyname,department,phone,country,customattribute1,customattribute2".  The list can be of any values valid for SSO configuration. Please see the sample below.

In Azure environments where additional attribute values are exposed to users with access tokens during SSO authentication, users can pass this information via JWT. Values that are not exposed will be shown as null in JWT.

Troubleshooting

If you need more details to see what WEB API is receiving as an access token from the user, you can create the WEB API application's new setting "verboselog" with the value "true" to see details of claim information received by WEB API from SPA.

When verbose logging is enabled, you can find more detailed events on SSO claim values received from users during login in the WEB API log stream console.

Deployment video

The below deployment video shows how to deploy WEB API AWS Connect web application service and SSO user interface (UI) for AWS Connect PaaS service to provide an end-to-end solution for identifying callers authenticated with the Identity provider and personalizing the web chat experience via a single-page application (SPA) hosting AWS Connect chat widget Javascript (JS) code.