Optimizing AWS Amplify and Cognito Integration with AWS CDK

AWS Amplify + Amazon Cognito + AWS CDK: A Complete Setup Guide

Setting up AWS Amplify with Amazon Cognito via CDK requires navigating specific integration hurdles like GitHub App migrations and SES permissions. While Level 1 CloudFormation constructs simplify basic setup, developers must handle manual console prompts for GitHub authentication and CLI workarounds for UI branding.

Why This Matters

The technical reality of AWS CDK is that while it provides robust infrastructure-as-code for resource provisioning, UI-level configurations like Cognito’s New Managed Login branding are not yet natively supported. This creates a friction point between ideal ‘everything-as-code’ models and the practical necessity of using the AWS CLI to sync branding JSON files during CI/CD pipelines. Failing to automate these steps leads to inconsistent user experiences across environments where branding must be manually applied via the AWS Console.

Key Insights

• CDK GitHub integration initially requires a Personal Access Token (PAT), which must be migrated to GitHub App authentication in the Amplify console post-deployment.
• Configuring signInAliases with email: true in Cognito User Pools allows email-based login and automatically renders the username as the email in notification templates.
• SES identities used for Cognito email must be moved out of sandbox mode and explicitly granted ‘ses:SendEmail’ permissions via an ArnPrincipal for the User Pool.
• Nuxt.js SSR applications require ‘generateSecret: true’ and ‘authorizationCodeGrant’ in the UserPoolClient to maintain secure server-side authentication flows.
• Cognito Managed Login branding can be automated by exporting settings via ‘aws cognito-idp describe-managed-login-branding’ and applying them in CI/CD via the update command.

Working Examples

Cognito User Pool configuration with email-only login and custom HTML templates.

new cognito.UserPool(this, 'MyUserPool', {
signInAliases: { email: true },
autoVerify: { email: true },
standardAttributes: {
email: { required: true, mutable: true },
givenName: { required: false, mutable: true },
familyName: { required: false, mutable: true },
},
userInvitation: {
emailSubject: 'Access to My App',
emailBody: "Hello,<br>Your username: {username}<br>Password: {####}",
},
userVerification: {
emailSubject: 'Verification Code',
emailBody: 'Your verification code: {####}',
},
accountRecovery: cognito.AccountRecovery.EMAIL_ONLY,
});

UserPoolClient setup for SSR frameworks like Nuxt requiring client secrets and authorization code grants.

new cognito.UserPoolClient(this, 'Client', {
userPool,
generateSecret: true,
preventUserExistenceErrors: true,
supportedIdentityProviders: [
cognito.UserPoolClientIdentityProvider.COGNITO,
],
oAuth: {
callbackUrls: ['https://myapp.com/auth/callback'],
logoutUrls: ['https://myapp.com'],
scopes: [
cognito.OAuthScope.OPENID,
cognito.OAuthScope.PROFILE,
],
flows: {
authorizationCodeGrant: true,
implicitCodeGrant: true,
},
},
});

CLI workaround for applying Cognito branding that is not currently supported in CDK.

aws cognito-idp update-managed-login-branding \
--user-pool-id $USER_POOL_ID \
--managed-login-branding-id $MANAGED_LOGIN_BRANDING_ID \
--settings file://login-settings.json

Practical Applications

• System: Nuxt SSR Framework - Use case: Implementing secure auth by setting ‘generateSecret: true’ to allow server-side token exchange. Pitfall: Forgetting to enable ‘authorizationCodeGrant’ leads to insecure token handling in the browser.
• System: Multi-regional Identity - Use case: Localizing the login UI using the ‘lang’ parameter in Nuxt’s authorizationParams. Pitfall: Relying on standard attributes for search functions; custom attributes in Cognito are not searchable.
• System: Automated Deployment - Use case: Using the AWS CLI in GitHub Actions to apply branding JSON after CDK deployment. Pitfall: Leaving SES in sandbox mode prevents delivery of invitation emails to external users.

References:

• https://dev.to/aws-builders/aws-amplify-amazon-cognito-aws-cdk-a-complete-setup-guide-26f2