|
1 | | -## My Project |
| 1 | +# Amazon Connect Global Resiliency dashboard starter project |
2 | 2 |
|
3 | | -TODO: Fill this README out! |
| 3 | +>**BE AWARE:** This code base is an [Open Source](LICENSE) starter project designed to provide a demonstration and a base to start from for specific use cases. |
| 4 | +It should not be considered fully Production-ready. |
| 5 | +If you plan to deploy and use this in a Production environment please review the [Using this in Production](#using-this-in-production) section at the end for some additional guidance. |
4 | 6 |
|
5 | | -Be sure to: |
| 7 | +## Use-case scenario |
| 8 | + |
| 9 | +[Amazon Connect](https://docs.aws.amazon.com/connect/latest/adminguide/what-is-amazon-connect.html) is an omnichannel cloud contact center that allows you to set up a contact center in just a few steps. |
| 10 | + |
| 11 | +Using [Amazon Connect Global Resiliency](https://docs.aws.amazon.com/connect/latest/adminguide/setup-connect-global-resiliency.html) you can link an Amazon Connect instance to one in another AWS Region and provision and manage phone numbers that are global and accessible in both Regions. |
| 12 | +You can distribute traffic between instances in 10% increments allowing failover between regions. |
| 13 | + |
| 14 | +Currently you can interact with these features through the AWS CLI or APIs. |
| 15 | +This is a starter project that demonstrates and provides a starting point for how you can build a dashboard that can interact with Amazon Connect's Global Resiliency features through a UI instead. |
| 16 | + |
| 17 | +**Before using the Amazon Connect Global Resiliency features through this dashboard you should review the [requirements](https://docs.aws.amazon.com/connect/latest/adminguide/get-started-connect-global-resiliency.html) and pricing for Amazon Connect. |
| 18 | +You may need to engage with your Account team in order to enable these features.** |
| 19 | + |
| 20 | + |
| 21 | +## The dashboard |
| 22 | +The dashboard provides screens that let you navigate through and replicate your instances, view and create traffic distribution groups, and view and associate phone numbers to them. It also lets you redistribute the traffic between instances. |
| 23 | + |
| 24 | + |
| 25 | + |
| 26 | + |
| 27 | +### Key limitations |
| 28 | +- Once an instance has been replicated it will be empty. You will need to use the AWS Console (and Amazon Connect console) to configure it.. |
| 29 | +- You cannot claim new numbers from the dashboard, only move them into and out of your traffic distribution group. |
| 30 | +- You cannot associate numbers to queues from the dashboard, please ensure any phone numbers moved to your traffic distribution groups are associated to queues on both instances through the standard Amazon Connect dashboard. |
| 31 | +- Certain actions can only be taken on the source Connect instance and not on the replica created from it, for instance adding TDGs and assigning numbers to a TDG. This is a limitation of the APIs themselves. |
| 32 | +Please ensure that you have all your configuration set up prior to needing failover. |
| 33 | +Check the [docs](https://docs.aws.amazon.com/connect/latest/adminguide/setup-connect-global-resiliency.html) for more details on specific operations. |
| 34 | +(NOTE: you **can** distribute traffic between instances from either instance). |
| 35 | + |
| 36 | +> This application MUST be deployed into **both regions** where your linked Amazon Connect instances are. This is necessary for a failover situation where you might not be able to access one of the environments. |
| 37 | +
|
| 38 | + |
| 39 | + |
| 40 | +---- |
| 41 | + |
| 42 | +## Solution components |
| 43 | + |
| 44 | +On a high-level, the solution consists of the following components, each contained in these folders: |
| 45 | + |
| 46 | +* **website** - The dashboard front-end written in React |
| 47 | +* **cdk-stacks** - AWS CDK stacks: |
| 48 | + - `cdk-backend-stack` with all the backend resources needed for the solution (AWS Lambda, Amazon API Gateway, Amazon Cognito, etc) |
| 49 | + - `cdk-front-end-stack` with front-end resources for hosting the webapp (Amazon S3, Amazon CloudFront distribution) |
| 50 | + |
| 51 | + |
| 52 | +### Solution architecture: |
| 53 | + |
| 54 | + |
| 55 | + |
| 56 | + |
| 57 | +## Solution prerequisites |
| 58 | +* AWS Account |
| 59 | +* [AWS IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) with Administrator permissions |
| 60 | +* Amazon Connect instance (SSO/SAML enabled) |
| 61 | +* [Node](https://nodejs.org/) (v16) and [NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (v8.5) installed and configured on your computer |
| 62 | +* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) (v2) installed and configured on your computer |
| 63 | +* [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) (v2) installed and configured on your computer |
| 64 | + |
| 65 | +## Solution setup |
| 66 | + |
| 67 | +The below instructions show how to deploy the solution using AWS CDK CLI. If you are using a Windows device please use the [Git BASH](https://gitforwindows.org/) terminal |
| 68 | +and use alternative commands where highlighted. |
| 69 | + |
| 70 | +These instructions assume you have completed all the prerequisites, and you have an existing Amazon Connect instance with SSO/SAML enabled. |
| 71 | + |
| 72 | +1. Clone the solution to your computer (using `git clone`) |
| 73 | + |
| 74 | +2. Check AWS CLI |
| 75 | + - AWS CDK will use AWS CLI local credentials and region |
| 76 | + - check your AWS CLI configuration by running an AWS CLI command (e.g. `aws s3 ls`) |
| 77 | + - you can also use profiles (i.e. `export AWS_PROFILE=<<yourProfile>>`) |
| 78 | + - you can confirm the configured region with |
| 79 | + `aws ec2 describe-availability-zones --output text --query 'AvailabilityZones[0].[RegionName]'` |
| 80 | + |
| 81 | + |
| 82 | +3. Install NPM packages |
| 83 | + - Open your Terminal and navigate to `amazon-connect-global-resiliency/cdk-stacks` |
| 84 | + - Run `npm run install:all` |
| 85 | + - This script goes through all packages of the solution and installs necessary modules (webapp, cdk-stacks, lambdas, lambda-layers) |
| 86 | + |
| 87 | + |
| 88 | +4. Configure CDK stacks |
| 89 | + - In your terminal, navigate to `amazon-connect-global-resiliency/cdk-stacks` |
| 90 | + - To see the full instructions for the configuration script, run |
| 91 | + `node configure.js -h` |
| 92 | + - For the purpose of this guide, start the configuration script in interactive mode which will guide you through each input one at a time. |
| 93 | + (Note, it is possible to configure it via single command, by directly providing parameters, as described in the script help instructions) |
| 94 | + |
| 95 | + `node configure.js -i` |
| 96 | + - When prompted, provide the following parameters: |
| 97 | + - `cognito-domain-prefix`: Amazon Cognito hosted UI domain prefix, where users will be redirected during the login process. |
| 98 | + The domain prefix has to be unique. It can include only lowercase letters, numbers, and hyphens. Do not use a hyphen for the first or last character. Use periods to separate subdomain names. You can't use the text aws, amazon, or cognito in the domain prefix. |
| 99 | + - `webapp-api-allowed-origins`: Allowed Origins for web app APIs, please keep * at this point, we will come back to it once our front-end is deployed. |
| 100 | + - `cognito-saml-enabled`: as a starting point, set this parameter to `false`. _(If setting to `true`, please review the help instructions for information on additional parameters you will need to fill out: `node configure.js -h`)_ |
| 101 | + |
| 102 | + |
| 103 | +5. Deploy CDK stacks |
| 104 | + - In your terminal, navigate to navigate to `amazon-connect-global-resiliency/cdk-stacks` |
| 105 | + - Run the script: `npm run build:frontend` (remember to complete this step whenever you want to deploy new front end changes) |
| 106 | + - **On Windows devices use `npm run build:frontend:gitbash`**. |
| 107 | + - This script builds frontend applications (webapp) |
| 108 | + - If you have started with a new environment, please bootstrap CDK: `cdk bootstrap` |
| 109 | + - Run the script: `npm run cdk:deploy` |
| 110 | + - This script deploys CDK stacks |
| 111 | + - Wait for all resources to be provisioned before continuing to the next step |
| 112 | + - AWS CDK output will be provided in your Terminal. You should see the Amazon Cognito User Pool Id as `userPoolId` from your Backend stack, |
| 113 | + and Amazon CloudFront Distribution URL as `webAppURL` from your Frontend stack. |
| 114 | + **Save these values as you will be using them in the next few steps.** |
| 115 | + |
| 116 | + |
| 117 | +6. Create Cognito User |
| 118 | + - To create an Amazon Cognito user, you'll need Cognito User Pool Id (created in step 5 - check for the AWS CDK Output, or check it in your AWS Console > Cognito User Pools) |
| 119 | + - Create an Amazon Cognito user either user directly in the [Cognito Console](https://docs.aws.amazon.com/cognito/latest/developerguide/how-to-create-user-accounts.html#creating-a-new-user-using-the-users-tab) or by executing: |
| 120 | + `aws cognito-idp admin-create-user --region <<yourDesiredRegion>> --user-pool-id <<yourUserPoolId>> --username <<yourEmailAddress>> --user-attributes "Name=name,Value=<<YourName>>" --desired-delivery-mediums EMAIL` |
| 121 | + - You will receive an email, with a temporary password, which you will need in step 7 |
| 122 | + **You can repeat this step for each person you want to give access to either now or at a later date. Remember to create each user in both regions** |
| 123 | + |
| 124 | + |
| 125 | +7. Configure API Allowed Origins (optional) |
| 126 | + - Cross-origin resource sharing (CORS) is a browser security feature that restricts cross-origin HTTP requests that are initiated from scripts running in the browser. At this point, we can restrict our APIs to be accessible only from our Amazon CloudFront Distribution domain (origin). |
| 127 | + - In your terminal, navigate to `amazon-connect-global-resiliency/cdk-stacks` |
| 128 | + - Start the configuration script in interactive mode, with additional `-l` (load) parameter |
| 129 | + `node configure.js -i -l` |
| 130 | + - The script loads all the existing parameters, and prompts for new parameters to be provided |
| 131 | + - Accept all the existing parameters, but provide a new value for: |
| 132 | + - webapp-api-allowed-origins: Domain of your agent application, in this case Amazon CloudFront Distribution URL. For instance: `https://aaaabbbbcccc.cloudfront.net` |
| 133 | + - The script stores the deployment parameters to AWS System Manager Parameter Store |
| 134 | + - While in `amazon-connect-global-resiliency/cdk-stacks`, run the deploy script: `npm run cdk:deploy` |
| 135 | + - Wait for the CDK stacks to be updated |
| 136 | + |
| 137 | + |
| 138 | +8. Test the solution |
| 139 | + - Open your browser and navigate to Amazon CloudFront Distribution URL (Output to the console and also available in the Outputs of the Frontend Cloudformation Stack) |
| 140 | + - On the Login screen, provide your email address and temporary password you received via email |
| 141 | + - If logging in the first time you will be prompted to reset your password. |
| 142 | + - You should now see a list of your Amazon Connect instances and be able to select one and interact with the Global Resiliency features. You can learn more about the screens from the [User Guide](./Amazon-Connect-Global-Resiliency-Dashboard-User-Guide-v1.pdf). |
| 143 | + |
| 144 | + |
| 145 | +9. Deploy your solution into the second region |
| 146 | + - Switch the region either in your profile or alternatively in your CLI using `export AWS_DEFAULT_REGION=<<desiredregion>>` |
| 147 | + - You can confirm the configured region with |
| 148 | + `aws ec2 describe-availability-zones --output text --query 'AvailabilityZones[0].[RegionName]'`- |
| 149 | + - Rerun steps 4-8 to deploy into the second region |
| 150 | + |
| 151 | + |
| 152 | + |
| 153 | +## Clean up |
| 154 | + |
| 155 | +To remove the solution from your account, please follow these steps in each region you have deployed into: |
| 156 | + |
| 157 | +1. Remove CDK Stacks |
| 158 | + - Run `cdk destroy --all` |
| 159 | + |
| 160 | +1. Remove deployment parameters from AWS System Manager Parameter Store |
| 161 | + - Run `node configure.js -d` |
| 162 | + |
| 163 | + |
| 164 | +--- |
| 165 | + |
| 166 | +## Using this in Production |
| 167 | + |
| 168 | +It is critical that before you use any of this code in Production that you work with your own internal Security and Governance teams to get the appropriate Code and AppSec reviews for your organization. |
| 169 | + |
| 170 | +Although the code has been written with best practices in mind, your own company may require different ones, or have additional rules and restrictions. |
| 171 | + |
| 172 | +You take full ownership and responsibility for the code running in your environment, and are free to make whatever changes you need to. |
| 173 | + |
| 174 | +>It is critical that you test this solution once deployed AND incorporate frequent failover tests throughout the year as part of your organization's larger Disaster Recovery Drills. |
| 175 | +
|
| 176 | +**Some of the things you will want to consider** |
| 177 | +- The starter project has extensive logging to CloudWatch, but does not have any monitoring or tracing included, you may want to look at using tools like Cloudwatch Alarms and X-ray. |
| 178 | +- The starter project uses Cognito user pools, but you may want to consider using Cognito identity pools (federated identities) to connect it to your current identity providers. |
| 179 | +- If you decide to use Cognito, you will want to check the password policy matches your expectations and you may want to enable MFA. |
| 180 | +- The starter project only provides access through Cloudfront, you will likely want to integrate it with a firewall like AWS WAF, and should verify if any restrictions should be added to your Cloudfront distribution (e.g. geo restrictions). |
| 181 | +- The starter project does not currently have tags on any resources |
6 | 182 |
|
7 | | -* Change the title in this README |
8 | | -* Edit your repository description on GitHub |
9 | 183 |
|
10 | | -## Security |
11 | 184 |
|
12 | | -See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. |
13 | 185 |
|
14 | | -## License |
15 | 186 |
|
16 | | -This library is licensed under the MIT-0 License. See the LICENSE file. |
17 | 187 |
|
0 commit comments