Skip to main content

Cognito Stack

Overview​

Cognito is AWS user authentication and authorisation service. This package creates the userpools and configuration for Platform

To Setup​

  • install AWS CDK Globally npm install -g aws-cdk@latest
  • Bootstrap the account cdk bootstrap aws://[ACCOUNT_ID]/eu-west-2 this will set up the CDK resources required to manage AWS resources via the CDK
  • Ensure you have ~/.aws/credentials set up, or use aws configure to set up, will use default profile by, er default export AWS_PROFILE=<profile-to-use> if you don't want to use the default one
  • to generate the CF Template run npm run [ENVIRONMENT]-synth
  • to deploy npm run [ENVIRONMENT]-deploy
  • Will deploy user pool named cognito-[ENVIRONMENT]-[VERSION]

Versioning​

The Cognito stack is versioned, if you need to deploy a new version of the stack and migrate users to it you need to change the Cognito version the scripts in package.json as well as the HCTR_COGNITO_VERSION GitHub secret. The version number if GitHub is v1 for example

After doing so when you next deploy the Cognito stack the version number will be changed and an entire new stack will be deployed and users will start (once the services are deployed with the updated Cognito user pool id and client id) to be created in the new user pool.

We have an auto migration process in place where users are automatically migrated to the new user pool on login or password reset.

NB: If you create a new Cognito user pool you will need to migrate the sys admin user ([email protected]) as this user is used in the API clients for authentication of certain events. The user will be created automatically but you need to set a password

Resources​

  • Userpool
  • API Client
  • Admin user 1 [email protected]
  • Owner user 1 [email protected] (if stage is not prod)
  • Clear User Pool Lambda to clean up test user pool
  • SSM parameters that store userpool id and api client id for injection into deployment scripts. Format /cognito/<stage>/<version>/userpool/userpoolid & /<cognito/<stage>/<version>/userpool/clientId respectively
  • Userpool triggers
    • CustomEmailSender Trigger Lambda
    • CustomSMSSender Trigger Lambda
    • CustomAuthChallenge (Define)
    • CustomAuthChallenge (Create)
    • CustomAuthChallenge (Verify)

Cognito Userpool Triggers​

  • Custom[Email/SMS]Sender both send out customised messages via Courier for all user messages involving their account

Deployment​

Changes to the pool must be done via the deployment scripts in the .github folder. Reserved environment stages dev, uat, sandbox and prod

Bootstrapping​

Each AWS account and region that this code is being deployed into needs to firstly be bootstrapped. We have done this for our environments but if you are using a different account you will need to run cdk bootstrap aws://<account-number>/<region> before deploying

Permissions​

The deployment users for each environment have been given permissions to assume the CDK deployment role using the following inline policy (AssumeCDKRole)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor1",
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::*:role/cdk-*"
    }
  ]
}

Environment Variables​

The Lambda Triggers require a number of environment variables. Each is supplied either by the CDK stack itself or via the Github Action workflow (using variables from Github secrets)

if deploying locally (for testing), ensure these are set to the correct values

CDK Stack populated​

  • KEY_ARN - KMS Key ARN
  • KEY_ALIAS - KMS Key alias ARN

Useful commands​

  • cdk deploy deploy this stack to your default AWS account/region
  • cdk diff compare deployed stack with current state
  • cdk synth emits the synthesized CloudFormation template