ALB-Cognito Auth

This is demo repository for my Using ALB and Cognito to add authentication to your apps blog post.

How to deploy

1. Install dependencies

You can use mise to install all developer dependencies.

mise install

Then, install NodeJS dependencies:

yarn

2. Export AWS credentials to connect to the Shared Assets account in our console

3. Change the config values to fit your use-case

Change the src/config/config.dev.ts to fit your use case. The parameter samlMetadataUrl is optional, and if not provided, the authentication will be via Cognito User Pool; otherwise, if the parameter is passed, the authentication will be via SAML 2.0 using IAM Identity Center as IdP.

⚠️ The AWS does not support creating Identity Center applications programatically, meaning that the application should be created manually. I suggest first deploying the application without the samlMetadataUrl parameter, then proceeding to add it. This will be explained in the following steps.

4. Go to your application endpoint and check if it's redirecting you to log in via Cognito User Pool.

You can create a user in the user pool and validate that this user can actually log in to the application.

5. Deploy the DevWorkloadStack

yarn cdk deploy DevWorkloadStack

After the deployment, go to the AWS Console > CloudFormation > DevWorkloadStack > Resources > Copy the Physical ID of the CognitoAuthUserPool resource. We are going to use it on step 8.

6. Go to the AWS Identity Center

7. Select Application of type SAML 2.0

8. Configure the SAML 2.0 Application

• The Application Start URL should be set to: https://{appSubdomain}.{domainName}
• The Application ACS URL should be set to: https://{appSubdomain}.{domainName}/saml2/idpresponse. The Cognito documentation specificies the /saml2/idpresponse path.
• The Application SAML audience should be set to: urn:amazon:cognito:sp:{awsRegion}:{userPoolId} based on the Cognito documentation.

Make sure to substitute the variable in the brackets with the correct value:

• {appSubdomain}: The value used in your src/config/config.dev.ts file
• {domainName}: The value used in your src/config/config.dev.ts file
• {awsRegion}: The value used in your src/config/config.dev.ts file (env.region).
• {userPoolId}: The value you copied on step 4.

Copy the IAM Identity Center SAML metadata URL to use in the following step.

9. Edit attribute mapping

Map:

• Subject to ${user:subject} with persistent format.
• email to ${user:email} with basic` format.

10. Deploy the stack with the samlMetadataUrl

Add the samlMetadataUrl parameter to the src/config/config.dev.ts and then deploy the stack again:

yarn cdk deploy DevWorkloadStack

11. Assign the Application to the identity center user

12. Go to your application endpoint and check if it's redirecting you to log in via Identity Center.

⚠️ Even after the deployment is successful, it might take a couple of minutes for Cognito to redirect to Identity Center.

13. Check if the application is accessible after the login