documentation : update the documentation with recommendations

[awskaran]

What is the problem?

Updates to configuration of the app

Update the [instructions](https://github.com/HicResearch/treehoose-egress-app-backend/blob/main/README.md?plain=1#L39] for configuring cdk.json to address below points

• As a best practise use datalake_target_bucket_arn and datalake_target_bucket_kms_arn for storing approved egress request data in the Datalake account
• use_s3_access_points is a customisation which should not be used as default
• Change download_expiry_seconds from 3600 seconds to a low number like 30
• ig_workspaces_account is another customisation which should not be used as default as IG lead's workspace would be in the TRE project account

Add below additional details to use new features

Parameter Name	Description	Location	Logical ID in CloudFormation Stack
regional_web_acl_arn	ARN for the WebAcl to be associated with Cognito User Pool. This should be deployed in the same region as TRE project. This is the output of the Web Application Firewall add-on stack RegionalWebAclStack	Check AWS CloudFormation Outputs tab for Stack "RegionalWebAclStack"	oWebAclId
global_web_acl_arn	ARN for the WebAcl to be associated with Egress Web App. This should be deployed in N. Virginia region. This is the output of the Web Application Firewall add-on stack GlobalWebAclStack	Check AWS CloudFormation Outputs tab for Stack "GlobalWebAclStack"	oWebAclId

• Optional config to enable login to Egress app using Idp federation.
  The parameters below are in cdk.json under custom_idp.

Parameter Name	Description	Location	Logical ID in CloudFormation Stack
is_enabled	Set to true if custom IdP federation is required. false will disable it.	-	-
name	Set to the name you want for the custom IdP	To view resources created after deployment of this CDK stack, go to service Amazon Cognito	CustomIdentityProvider
metadata_url	Use the SAML metadata url for the identity provider. You can put in a dummmy value to start with and update later as there can be a cyclic dependency for the IdP configuration.	-	-

[ ] Optional config to serve Egress App frontend on custom domain.
This step assumes that you have deployed WebAcl, ACM and Route53 resources yourself.
The parameters below are in cdk.json under custom_domain.

Parameter Name	Description	Location	Logical ID in CloudFormation Stack
is_enabled	provide a boolean true or false. setting to true will deploy the required customisations to access the egress app at custom domain set below in domain_name parameter
domain_name	A subdomain under the route53 public hosted zone for the project on which egress app should be accessible
cert_arn	Arn for a project level wildcard certificate	Check AWS CloudFormation Outputs tab for Stack "ProjectDomainStack"	oProjectCertArn
hosted_zone_id	Id of the route53 public hosted zone for the project	Check AWS CloudFormation Outputs tab for Stack "ProjectDomainStack"	oHostedZoneId
hosted_zone_name	Name of the route53 public hosted zone for the project	Check AWS CloudFormation Outputs tab for Stack "ProjectDomainStack"	oProjectZoneName

• Update cdk version here to use cdkv2

Add below instructions to Configuration guide

Access Egress Web App with AWS IAM Identity Center (Optional)

---

The below instructions will be used to set up the
Egress App to use AWS IAM Identity Center (successor to AWS Single Sign-On) as the Identity Provider and
Cognito as the Service Provider.

AWS IAM Identity Center can act as a standalone IdP
or can be backed by another IdP.

Creating AWS IAM Identity Center App

---

• Log in to the AWS Management Console of the management account
  (or delegated IAM Identity Centre account)
  of the AWS Organization, using admin privileges.
  Switch to the region where AWS IAM Identity Center has
  been activated by AWS Control Tower.

• Navigate to Applications and click on Add application

• Under Custom application choose radio button for
  Add custom SAML 2.0 application. Scroll below and click Next.

• Provide a user friendly application name
  and description.

• Scroll down to see the IAM Identity Center metadata.
  Copy the url for IAM Identity Center SAML metadata file.
  We will use this in later step.

Configure Application properties

---

• Scroll down and provide application start
  url. The information to be replaced are
  from the output of the Egress App Backend deployment.
  The URL_FOR_WEBAPP will be different if the domain
  has been customised or using CloudFront.

  Property	Value
  Application start URL	https://CONGITO_DOMAIN.auth.REGION.amazoncognito.com/oauth2/authorize?redirect_uri=URL_FOR_WEBAPP&response_type=code&client_id=COGNITO_APP_CLIENT_ID&identity_provider=PROVIDER_NAME&scope=email%20openid%20profile%20aws.cognito.signin.user.admin

• Update Application metadata with values
  provided in below table. Update the highlighted
  values with the actual values.

  Property	Value
  Application ACS URL	https://congito-domain-name.auth.region.amazoncognito.com/saml2/idpresponse
  Application SAML audience	urn:amazon:cognito:sp:congito_userpool_id

• Click Submit which should create the
  new AWS SSO application.

Set up attribute mapping

---

• Click on Actions -> Edit attribute mappings
  for the new SSO application.

• Setup attribute mapping as described in below table

  User attribute in the application	Maps to this string value or user attribute in IAM Identity Center	Format
  Subject	${user:email}	emailAddress
  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	${user:givenName}	basic
  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	${user:name}	basic
  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	${user:familyName}	basic
  http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	${user:email}	basic

Assign users

---

• Click on Assign users to allow
  individual users or groups to use the Egress App.

Reproduction Steps

Not applicable

What did you expect to happen?

Not applicable

What actually happened?

Not applicable

TREEHOOSE version

main

Other information

No response