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
  • 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 see the CF Template run cdk synth -c prefix=<prefix>
  • to deploy cdk deploy --require-approval never --app 'cdk.out/' <stackName>
  • 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 in 2 places.

  1. infrastructure/cognito/bin/cognito.ts
  2. HCTR_COGNITO_VERSION Repository Secret in GitHub

When you next deploy the Cognito stack the version number will be changes 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.

Resources​

  • Userpool
  • API Client
  • Admin user 1 testing+dev@hectare.farm
  • Owner user 1 testing+pat.archer@hectare.farm (if stage is not prod)
  • 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

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, test, 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 folling 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

Github Populated​

  • SUPPORT_CONTACT_EMAIL - will be a hectare/farmto contact email
  • SUPPORT_CONTACT_PHONE - will be a hectare/farmto contact number
  • PLATFORM - platform name (defaults to FarmTo)
  • COURIER_API_KEY - Courier notifications api key
  • PLATFORM_BASE_URL - platform base url (env specific)

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