Code Genie | Blog

So long API Gateway, and thanks for all the routes

Thu, 19 Sep 2024 00:00:00 GMT

import { Image } from 'astro:assets'; import clefairy from '../../../assets/images/blog/so-long-api-gateway-and-thanks-for-all-the-routes/clefairy.gif' import lfurlWorkaroundTweets from '../../../assets/images/blog/so-long-api-gateway-and-thanks-for-all-the-routes/lfurl-workaround-tweets.png' import cognitoJwtVerifier from '../../../assets/images/blog/so-long-api-gateway-and-thanks-for-all-the-routes/cognito-jwt-verifier.png' import jwtExpressMiddleware from '../../../assets/images/blog/so-long-api-gateway-and-thanks-for-all-the-routes/jwt-express-middleware.png' import apigwLfurlClfurlPerformance from '../../../assets/images/blog/so-long-api-gateway-and-thanks-for-all-the-routes/apigw-lfurl-clfurl-performance.png' import codeGenieMaxDescription from '../../../assets/images/blog/so-long-api-gateway-and-thanks-for-all-the-routes/code-genie-max-description.png'

For nearly a decade I've been building APIs with API Gateway and Lambda. I was even fortunate enough to be part of the team that launched API Gateway back in 2015! It's served me well and I'm sure I'll use it again on future projects that require some of its more advanced features.

However, most of the time I just need a way to invoke a Lambda Function over HTTP with a custom domain name, and this is exactly what CloudFront + Lambda Function URL (CLFURL) enables.

Original image available in the blog post.

Clefairy: The unofficial mascot of CLFURL

Why change?

Cost

Since launch, one of the biggest criticisms of API Gateway has been its pricing. One would expect that Lambda (the thing that's doing the heavy lifting) would make up the majority of the cost, and not the thing that's simply connecting it to a client. In reality, API Gateway (even the newer, cheaper HTTP API variant) often exceeds Lambda costs by more than 2x. Under similar conditions, CloudFront costs ~10% of what Lambda does.

:::caution[WARNING: Gross oversimplification to prove a point detected] Saying API Gateway is just a service that connects Lambda over HTTP is unfair. Yan Cui has an excellent comparison of the two approaches in his blog post When to use API Gateway vs. Lambda Function URLs. He covers many of the advanced features of API Gateway and concludes with a preference for API Gateway in most scenarios. :::

The one area where API Gateway has a cost advantage is on unauthorized requests. When using its Authorizer feature, API Gateway eats those costs for you. With CLFURL you would pay both the CloudFront and Lambda costs for unauthorized requests. This is mostly only a concern when it comes to DDOS (or Denial of Wallet) attacks. Fortunately, AWS Shield Standard (a free DDOS protection service included with CloudFront) should mitigate those attacks.

Max timeout

API Gateway has a max timeout of 29 seconds, which is more than enough for most REST API needs. However, with AI becoming a core feature of many products, those extra 31 seconds afforded by CloudFront (a total of 1 minute) can be crucial.

In fact, this is the main reason I started investigating this option in the first place! Code Genie uses AI to generate data models based on the description of your app. There is currently a 500 character limit on this description to mitigate the chance of it taking longer than 29 seconds. By moving to CLFURL, Code Genie will be able to handle significantly more complex requests, and enable other AI features in the future.

500 characters is not enough to describe complex applications 😞

:::note[API Gateway max timeout can be increased on request] API Gateway recently announced it can increase the max timeout via support request. This is only available for Regional REST APIs (not the less-expensive HTTP API offering, or Edge-Optimized REST APIs). :::

Performance?

In my tests comparing the performance of API Gateway to CloudFront, I found both approaches yield similar results. Here are the highlights:

CloudFront adds a shocking +300ms latency for cross-region (other-side-of-the-world) requests when not under load. These findings are why I didn't switch to CLFURL earlier this year. I recently decided to test the performance again, hoping that AWS had resolved the issue. They hadn't. However, after diving deeper I discovered that this latency is akin to a cold start. When under load, this extra latency is a rare occurrence.
Under load, CloudFront offers marginally better performance than API Gateway HTTP API. ~4% faster on average. These tests were only run against the cheaper, faster HTTP API option. If you're using the original REST API option, you might see a more significant performance difference around the 20% mark (along with 3x the cost).

API Gateway vs Lambda Function URL vs CloudFront + LFURL

You can try it out yourself at https://production.d1gtqqp4ixg5qm.amplifyapp.com/public-api (no guarantees on how long this website will be live) or deploy your own version by cloning this repo https://github.com/CodeGenieApp/cloudfront-lambda-url-vs-apigw and running npm run init:dev

Locking down the Lambda FURL

If you want to enforce CloudFront security features such as Shield and WAF, you need to ensure attackers can't bypass CloudFront by calling your Lambda Function URL directly. To accomplish this, AWS recommends setting the LFURL's authorization to AWS_IAM and using OAC to grant access for the distribution. If only it were that simple. Unfortunately, there are two challenges with this:

CloudFront overrides the Authorization header when invoking your Lambda Function, so you need to use a different, non-standard header to include your auth token. You can use CloudFront Functions to copy the original Authorization header to a new header like X-Auth so that at least your clients can continue using the standard header name.
The client needs to sign the payload in PUT/POST methods. See this post by David Behroozi for more details.

A simpler solution proposed by Ryan Scott Brown is to have CloudFront add a custom origin header with a secret: 'X-CloudFront-Secret': 'NoBadGuysAllowed'. Your Lambda Function can check the secret in the header, and return an error code if it doesn't match. Another solution proposed by Andrea Amorosi uses Lambda@Edge. Since an attacker would need to discover both the Lambda Function URL and the secret before successfully bypassing CloudFront, this solution is likely more than enough for most applications.

Simpler solutions to locking down your Lambda FURL

Replacing API Gateway Authorizer with in-Lambda JWT validation

The only "advanced" API Gateway feature I use on all of my APIs is the Cognito/JWT Authorizer. Since CloudFront doesn't have a similar native feature, we need to perform the JWT validation inside the Lambda Function. This has the added bonus of making our app more portable and easier to run locally, while also granting us more flexibility.

Express Middleware for JWT validation

Cognito JWT Validation via aws-jwt-verify

Performing Cognito JWT validation yourself is also incredibly fast (~4ms cold; ~0.3ms warm in Node.js) thanks to this tip by David Behroozi.

Another option is to use a CloudFront Function to perform JWT validation. This has the benefit of rejecting the request before it makes it to your Lambda Function, at the cost of a little extra complexity and having to do some magic to get local development working.

Conclusion

CloudFront + Lambda Function URL (CLFURL) is an excellent combination for Serverless APIs when you don't need any of the advanced features offered by API Gateway. With CloudFront being an order of magnitude cheaper than API Gateway, it puts it more in line with what'd you'd expect when compared to the cost of other components of your Serverless architecture.

The minor performance improvement compared to HTTP API is nice, but likely to be unnoticeable to the end user (compared to REST API may be a different story). On the other hand, the increase in the max timeout will surely be appreciated by developers looking to add Generative AI to their API.

A repo is available at https://github.com/CodeGenieApp/cloudfront-lambda-url-vs-apigw. This repo was generated using Code Genie and modified to include CloudFront + Lambda Function URL and benchmarks. Check out the commit history to find the interesting parts.

Code Genie will soon offer CLFURL as an option when generating your source code, and will continue to support API Gateway HTTP APIs as well.

If you've found this blog useful, please give it a reshare! You can follow me and Code Genie on Twitter. Finally, if you're building something new (or want to refresh something old), be sure to check out Code Genie. It takes care of all the boring parts of starting a new project so you can focus on what's interesting!

Creating AWS CloudWatch Dashboards and Alarms with CDK

Fri, 12 Apr 2024 00:00:00 GMT

import { Image } from 'astro:assets' import { Tabs, TabItem } from '@astrojs/starlight/components' import demoDashboard from '../../../assets/images/blog/dashboard-1440.webp'

Monitoring is a crucial part of software operations, but can also be one of the most tedious to implement. If you're using a traditional config-based IAC tool such as CloudFormation, SAM, Serverless, Terraform, et al. you'll find yourself copy-pasting dozens of lines for each new metric that you want to graph and alert on.

Modern IAC tools such as CDK enable you to define your infrastructure using actual code (often TypeScript) rather than config (JSON, YAML). I like to refer to these two approaches to IAC as IACode and IAConfig respecively.

In this article we'll cover how to build a CloudWatch Dashboard and Alarms to monitor a Full Stack Serverless AWS application consisting of API Gateway, Lambda, Cognito, DynamoDB, and a web app hosted on Amplify Hosting. Here's what the end result looks like (though you'll need to use your imagination to fill in the empty charts with pretty lines).

Example dashboard that would look so much more interesting if it had actual data.

Monitoring Construct

Enough preamble. Let's get into the code! We'll start by creating a Monitoring construct that allows us to encapsulate all of the relevant infrastructure in a single place.

import { Construct } from 'constructs'
import {
  Alarm,
  AlarmRule,
  AlarmState,
  AlarmStatusWidget,
  CompositeAlarm,
  Dashboard,
  GraphWidget,
  Metric,
  TextWidget,
  TextWidgetBackground,
} from 'aws-cdk-lib/aws-cloudwatch'
import { IFunction } from 'aws-cdk-lib/aws-lambda'
import { IHttpApi } from 'aws-cdk-lib/aws-apigatewayv2'
import { IApp } from '@aws-cdk/aws-amplify-alpha'
import { ITableV2 } from 'aws-cdk-lib/aws-dynamodb'
import { Topic } from 'aws-cdk-lib/aws-sns'
import { EmailSubscription } from 'aws-cdk-lib/aws-sns-subscriptions'
import { SnsAction } from 'aws-cdk-lib/aws-cloudwatch-actions'

interface MonitoringProps {
  amplifyApp: IApp
  api: IHttpApi
  userPoolId: string
  userPoolClientId: string
  functions: Array<IFunction>
  tables: Array<ITableV2>
}

const ALARM_NOTIFICATION_EMAIL = 'you@example.com'

export default class Monitoring extends Construct {
  public readonly dashboard: Dashboard
  public readonly alarmSnsTopic: Topic
  constructor(scope: Construct, id: string, props: MonitoringProps) {
    super(scope, id)
    this.alarmSnsTopic = new Topic(scope, 'AlarmTopic')
    this.alarmSnsTopic.addSubscription(new EmailSubscription(ALARM_NOTIFICATION_EMAIL))
    this.dashboard = new Dashboard(this, 'Dashboard', {
      start: '-P10D',
    })

    const { alarms: apiAlarms } = this.addApiWidgets({ api: props.api })
    const { alarms: lambdaAlarms } = this.addLambdaWidgets({ functions: props.functions })
    this.addTableWidgets({ tables: props.tables })
    this.addCognitoWidgets({ userPoolId: props.userPoolId, userPoolClientId: props.userPoolClientId })
    this.addWebAppWidgets({ amplifyApp: props.amplifyApp })
    this.addAlarmStatusWidget({ alarms: [...apiAlarms, ...lambdaAlarms] })
  }

  addHeading(heading: string) {
    this.dashboard.addWidgets(
      new TextWidget({
        markdown: `# ${heading}`,
        width: 24,
        height: 1,
        background: TextWidgetBackground.TRANSPARENT,
      })
    )
  }

  subscribeAlarm(alarm: Alarm | CompositeAlarm) {
    alarm.addAlarmAction(new SnsAction(this.alarmSnsTopic))
  }
  /*
  ...
  */
}

The Monitoring construct class accepts details on other resources within our app such as our Amplify Hosting App, API Gateway, Cognito User Pool and Client, and a list of Lambda Functions and DynamoDB Tables that we want to monitor.

The constructor creates an SNS Topic that's set up to send an email whenever it receives a message (i.e whenever an alarm is triggered). Make sure you replace ALARM_NOTIFICATION_EMAIL with the email address you want to receive notifications.

:::note[Notifications] You can configure SNS to notify other services such as Slack or your Incident Response tool instead of email, however, that's not the focus of this blog. For solo/hobby projects, email is fine. :::

We're also creating the CloudWatch Dashboard resource and calling methods to add widgets and alarms (we'll get to the implementation of these next).

Finally, we have some helper methods for adding headings to our Dashboard and subscribing alarms to our SNS Topic.

Next we'll get into creating metrics, alarms, and dashboard widgets for our API Gateway resource.

API Gateway Metrics, Alarms and Dashboard Widgets

addApiWidgets({ api }: { api: IHttpApi }) {
  this.addHeading('API Gateway')
  const clientErrorsMetric = api.metricClientError()
  const serverErrorsMetric = api.metricServerError()
  const clientErrorsAlarm = clientErrorsMetric.createAlarm(this, 'ApiClientErrorsAlarm', {
    evaluationPeriods: 3,
    threshold: 10,
  })
  this.subscribeAlarm(clientErrorsAlarm)
  const serverErrorsAlarm = serverErrorsMetric.createAlarm(this, 'ApiServerErrorsAlarm', {
    evaluationPeriods: 1,
    threshold: 1,
  })
  this.subscribeAlarm(serverErrorsAlarm)

  this.dashboard.addWidgets(
    new GraphWidget({
      width: 12,
      left: [
        clientErrorsMetric,
        serverErrorsMetric,
      ],
      leftAnnotations: [
        clientErrorsAlarm.toAnnotation(),
        serverErrorsAlarm.toAnnotation(),
      ],
    }),
    new GraphWidget({
      width: 12,
      left: [
        api.metricLatency(),
        api.metricIntegrationLatency(),
      ],
    }),
    new GraphWidget({
      width: 12,
      left: [
        api.metricCount(),
      ],
    }),
    new GraphWidget({
      width: 12,
      left: [
        api.metricDataProcessed(),
      ],
    }),
  )

  return {
    alarms: [serverErrorsAlarm, clientErrorsAlarm],
  }
}

Many CDK Constructs come with helper metric* methods that return metrics for the most popular standard metrics of each AWS service. In API Gateway's case, all of the standard metrics we're interested in have these helper metrics. Thank you CDK Team! 🙏

We create alarms for both Client Errors and Server Errors. The thresholds are low and you should tweak them to meet your needs (maybe you don't want to alarm on Client Errors at all since they're often not actionable). We also add these error metrics to our dashboard and add "red lines" (horizontal annotations) so that we can see how close we get to breaching our alarms. Once again, the CDK Team shows great attention to detail by including a toAnnotation() method on their alarms to make this super easy! 🙌

:::tip[Short and Long alarms] A best practice for creating alarms is to create two flavors of each alarm: a short/spikey alarm and a long/continuous alarm. This allows you to set two different thresholds for different scenarios. For example, you may want to alarm if your average latency breaches 3 seconds in a single 5 minute evaluation period, OR if it remains above 1 second for several evaluation periods. We didn't include that here for brevity, however, CDK enables you to turn this into a repeatable pattern with ease. :::

We also add metrics for latency (consider adding alarms for this), number of requests, and amount of data processed.

Let's move onto Lambda.

Lambda Metrics, Alarms and Dashboard Widgets

The main difference with the Lambda metrics is that we're dealing with multiple Lambda Functions (as opposed to a single API Gateway Resource). Each graph includes the metrics for all of the Lambda Functions passed into the Monitoring construct.

addLambdaWidgets({ functions }: { functions: Array<IFunction> }) {
  this.addHeading('Lambda Functions')
  const errorMetrics = functions.map(fn => ({ fn, metric: fn.metricErrors()}))
  const throttleMetrics = functions.map(fn => ({ fn, metric: fn.metricThrottles()}))
  const errorAlarms = errorMetrics.map(errorMetric => errorMetric.metric.createAlarm(this, `ErrorAlarm${errorMetric.fn.node.id}`, {
    evaluationPeriods: 1,
    threshold: 1,
  }))
  const throttleAlarms = throttleMetrics.map(throttleMetric => throttleMetric.metric.createAlarm(this, `ThrottleAlarm${throttleMetric.fn.node.id}`, {
    evaluationPeriods: 1,
    threshold: 1,
  }))
  const errorCompositeAlarm = new CompositeAlarm(this, 'ErrorCompositeAlarm', {
    alarmRule: AlarmRule.anyOf(
      ...errorAlarms.map(errorAlarm => AlarmRule.fromAlarm(errorAlarm, AlarmState.ALARM)),
      ...throttleAlarms.map(throttleAlarm => AlarmRule.fromAlarm(throttleAlarm, AlarmState.ALARM)),
    ),
  })
  this.subscribeAlarm(errorCompositeAlarm)
  this.dashboard.addWidgets(
    new GraphWidget({
      width: 8,
      left: [
        // Alternatively, you could use `functions.map` to instead create one GraphWidget per function.
        ...functions.map(fn => fn.metricDuration()),
        ...functions.map(fn => fn.metricDuration({
          statistic: 'P95',
        })),
      ],
    }),
    new GraphWidget({
      width: 8,
      left: functions.map(fn => fn.metricInvocations()),
    }),
    new GraphWidget({
      width: 8,
      left: errorMetrics.map(m => m.metric),
      right: throttleMetrics.map(m => m.metric),
      leftAnnotations: [errorAlarms[0].toAnnotation()],
    }),
  )

  return {
    alarms: [...errorAlarms, ...throttleAlarms],
  }
}

The metrics we're graphing are duration (both average and P95), number of invocations, number of errors, and number of times a function was throttled. We're only alarming on the error and throttle metrics here, though you should also consider alarming on duration.

We're creating 2 alarms per Lambda Function for throttle and error. These alarms aren't set up to notify. Instead, we create a composite alarm so that we don't get inundated with notifications when a single issue causes multiple functions to fail.

:::caution[Pricing] Alarms cost $0.10 per month (though you get 10 free) and the composite alarm costs $0.50 a month. If you don't want to have N alarms per function, Lambda also emits standard metrics that cover ALL Lambda Functions within your account. This is a viable option if you're following the best practice of only running a single App within an AWS Account. :::

See the Lambda Metrics Documentation for other available standard metrics.

DynamoDB Metrics and Dashboard Widgets

There's nothing new to learn here that isn't covered by the Lambda section. For each DynamoDB Table provided we're graphing the number of consumed Read and Write Capacity Units, and the number of User Errors.

addTableWidgets({ tables }: { tables: Array<ITableV2> }) {
  this.addHeading('DynamoDB Tables')
  this.dashboard.addWidgets(
    new GraphWidget({
      width: 8,
      left: tables.map(table => table.metricConsumedReadCapacityUnits()),
    }),
    new GraphWidget({
      width: 8,
      left: tables.map(table => table.metricConsumedWriteCapacityUnits()),
    }),
    new GraphWidget({
      width: 8,
      left: tables.map(table => table.metricUserErrors()),
    }),
  )
}

Consider adding an alarm for the UserErrors metric since it's likely due to a bug in your code. If you're not using DynamoDB's On Demand billing, you should also consider adding alarms for RCUs and WCUs.

DynamoDB offers significantly more standard metrics than most AWS Services, so you should definitely familiarize yourself with them and decide what's important for you to graph and alarm on. But don't go overboard! It's important to find the right balance between alarming on too many things and not enough.

:::tip If it's not actionable, don't alarm on it. :::

See the DynamoDB Metrics Documentation for other available standard metrics.

Cognito Metrics and Dashboard Widgets

Adding Cognito User Pools graphs gives great insights on the number of new and returning users. You may even be able to use the TokenRefreshSuccesses metric to get a rough number of currently active users.

addCognitoWidgets({ userPoolId, userPoolClientId }: { userPoolId: string, userPoolClientId: string }) {
  this.addHeading('Cognito')
  const dimensionsMap = {
    UserPool: userPoolId,
    UserPoolClient: userPoolClientId,
  }
  this.dashboard.addWidgets(
    new GraphWidget({
      width: 8,
      left: [new Metric({
        namespace: 'AWS/Cognito',
        metricName: 'TokenRefreshSuccesses',
        dimensionsMap,
      })],
    }),
    new GraphWidget({
      width: 8,
      left: [new Metric({
        namespace: 'AWS/Cognito',
        metricName: 'SignUpSuccesses',
        dimensionsMap,
      })],
    }),
    new GraphWidget({
      width: 8,
      left: [
        new Metric({
          namespace: 'AWS/Cognito',
          metricName: 'SignInSuccesses',
          dimensionsMap,
        }),
        new Metric({
          namespace: 'AWS/Cognito',
          metricName: 'FederationSuccesses',
          dimensionsMap,
        }),
      ],
    }),
  )
}

Unfortunately, the Cognito User Pool Construct doesn't have those handy metric* methods, so we need to manually create them using new Metric.

See the Cognito Metrics Documentation for other available standard metrics.

Amplify Hosting Metrics and Dashboard Widgets

I've encountered way too many people that don't know about Amplify Hosting. If you need to host a web app on AWS: I highly recommend Amplify Hosting over the more traditional approach of S3 + CloudFront.

addWebAppWidgets({ amplifyApp }: { amplifyApp: IApp }) {
  this.addHeading('Web App')
  const dimensionsMap = {
    App: amplifyApp.appId,
  }
  this.dashboard.addWidgets(
    new GraphWidget({
      width: 12,
      left: [new Metric({
        namespace: 'AWS/AmplifyHosting',
        metricName: 'Requests',
        dimensionsMap,
      })],
    }),
    new GraphWidget({
      width: 12,
      left: [new Metric({
        namespace: 'AWS/AmplifyHosting',
        metricName: 'Latency',
        dimensionsMap,
      })],
    }),
    new GraphWidget({
      width: 12,
      left: [new Metric({
        namespace: 'AWS/AmplifyHosting',
        metricName: 'BytesDownloaded',
        dimensionsMap,
      }),
      new Metric({
        namespace: 'AWS/AmplifyHosting',
        metricName: 'BytesUploaded',
        dimensionsMap,
      })],
    }),
    new GraphWidget({
      width: 12,
      left: [
        new Metric({
          namespace: 'AWS/AmplifyHosting',
          metricName: '4xxErrors',
          dimensionsMap,
        }),
        new Metric({
          namespace: 'AWS/AmplifyHosting',
          metricName: '5xxErrors',
          dimensionsMap,
        }),
      ],
    }),
  )
}

Alarm Status Dashboard Widget

Finally we'll display a list of our alarms and their current status.

addAlarmStatusWidget({ alarms }: { alarms: Array<Alarm> }) {
  this.addHeading('Alarms')
  const alarmStatusWidgetHeight = 1 + Math.ceil(alarms.length / 6)
  this.dashboard.addWidgets(new AlarmStatusWidget({
    alarms,
    width: 24,
    height: alarmStatusWidgetHeight,
  }))
}

You should also check out the other CDK CloudWatch Dashboard Widgets. The LogQueryWidget is especially useful for adding a quickview of logs that can be filtered using query insights (e.g. you can display the latest error logs).

Using the Construct

Now that we've created the Monitoring construct, we can add it to our CDK stack by instantiating an instance and passing in details about our full stack application.

new Monitoring(this, 'Monitoring', {
  userPoolId: userPool.userPoolId,
  userPoolClientId: userPoolClient.userPoolClientId,
  amplifyApp: amplifyApp,
  api: api,
  functions: [lambdaFunction1, lambdaFunction2],
  tables: [dynamoDbTable1, dynamoDbTable2],
})

A note on laying out widgets

CloudWatch Dashboards are rendered as a 24 column layout. Keep this in mind when deciding on the width of each widget.

According to the docs, every widget included in a single addWidgets is rendered next to each other, and every new call to addWidgets creates a new row. In practice, I found that when my widgets within a single addWidgets didn't add up to a multiple of 24, the layout started to go a little wonky, and widgets that I expected to be rendered in a new row (because they were in a separate addWidgets) were not.

There are Row and Column constructs that can also give you more control over layout.

Custom Metrics

Graphing and alarming on the standard metrics that AWS provides us with out-of-the-box is only half the story. To improve your "operational excellence" you'll want to add Custom Metrics relevant to your business requirements.

Try it yourself with Code Genie

Building a full stack Serverless app on AWS takes a lot of time, effort, and expertise. Code Genie lets you get up and running fast with a solid software foundation based on your data model. In minutes you can have a full stack application deployed to your own AWS account, and the source code downloaded for you to start hacking. Metrics, Monitoring, and a Dashboard like the one described in this article is included out-of-the-box. Check out the Getting Started Guide for more details.

AWS Cognito User Pools: Add Auth to a React App

Sat, 02 Mar 2024 00:00:00 GMT

import { Image } from 'astro:assets'; import { Tabs, TabItem } from '@astrojs/starlight/components' import signInPage from '../../../assets/images/blog/aws-cognito-google-sso-saml-linked-accounts/cognito-example-sign-in.webp';

Pretty picture of the Login UI.

Cognito User Pools is an AWS service that provides applications with user identity and auth. This series of articles cover a full stack solution that enables users to sign in with their Email + Password, Google Sign In, or SSO (SAML), and link all methods to the same user within the app:

Create Resources with CDK
Sign in with Email, Google, or SAML and link to a single user
Add Auth to a React App 👈 You are here

This article focuses on integrating Cognito User Pools with a React (Next.js) Web App, though the fundamentals remain the same for all frameworks. The example also uses the Ant Design UI Framework to make everything look good.

:::tip The complete source code is available by generating a Code Genie app and specifying 'Google' and 'SAML' idp options:

npx @codegenie/cli generate --name "Todo" \
--idp 'Google' --idp 'SAML' \
--description "A todo list app that lets users create lists and add items to the list. Items should have a title, description, be markable as completed, have a due date, and have an image."

Code Genie generates a Full Stack AWS Serverless application based on your own data model, including a React (Next.js) Web App, Serverless Express REST API, DynamoDB Database, and Cognito Auth. :::

React Cognito Auth

To add Cognito Auth to our React web app (specifically Next.js in this case) we'll use the Amplify JavaScript Library, which simplifies the complex OAuth flow.

The work required boils down to:

Configuring the Amplify library with details about our Cognito User Pool
Configuring Axios with the base URL of our API endpoint, and attaching the Authorizers header on each API request.
Adding pages for Login, Register, Verify, Forgot Password, Reset Password. See Code Genie pages docs for more details.
Wrapping each of the Amplify methods we use with TanStack Query useQuery hooks for improved state management. See Code Genie hooks docs for more details.

_app.tsx

import { Amplify } from 'aws-amplify'
import { fetchAuthSession } from 'aws-amplify/auth'
import axios from 'axios'

const oauthRedirectUrl = ['http://localhost:3001/']

if (global.window?.location.origin) oauthRedirectUrl.push(global.window.location.origin)

Amplify.configure({
  Auth: {
    Cognito: {
      userPoolId: process.env.NEXT_PUBLIC_CognitoUserPoolId!,
      userPoolClientId: process.env.NEXT_PUBLIC_CognitoUserPoolClientId!,
      loginWith: {
        oauth: {
          redirectSignIn: oauthRedirectUrl,
          redirectSignOut: oauthRedirectUrl,
          // replace 'example' with the regionallyUniqueDomainPrefix value defined in CDK
          domain: 'example.auth.us-west-2.amazoncognito.com',
          responseType: 'code',
          scopes: ['aws.cognito.signin.user.admin', 'email', 'openid', 'phone', 'profile'],
        },
      },
    },
  },
}, {
  ssr: false,
})

axios.defaults.baseURL = process.env.NEXT_PUBLIC_ApiEndpoint

// Set Authorization header on all requests if user is signed in; othwerise, redirect to login page
axios.interceptors.request.use(async (config) => {
  try {
    const authSession = await fetchAuthSession()
    config.headers.Authorization = authSession.tokens?.idToken?.toString()
  } catch (e) {
    const redirectRoute = getRedirectToLoginPageUrl()
    global.window.location.href = redirectRoute
  }

  return config
})
...

Login Page

import React, { useEffect, useRef } from 'react'
import {
  Button,
  Checkbox,
  Divider,
  Form,
  Input,
  InputRef,
  Typography,
} from 'antd'
import Link from 'next/link'
import UnauthenticatedPage from '../components/layouts/UnauthenticatedPage'
import { useSignInMutation, useSignInWithGoogleMutation, useSignInWithSsoMutation } from '../components/Me/meHooks'
import { useRouter } from 'next/router'
import { GoogleOutlined, LockOutlined } from '@ant-design/icons'

export default function LoginPage() {
  const [form] = Form.useForm()
  const passwordInputRef = useRef<InputRef>(null)
  const signInMutation = useSignInMutation()
  const signInWithGoogleMutation = useSignInWithGoogleMutation()
  const signInWithSsoMutation = useSignInWithSsoMutation()
  const router = useRouter()
  const queryParamEmail = (router.query.email as string) || ''
  const isSigningIn = signInMutation.isLoading || signInWithGoogleMutation.isLoading || signInWithSsoMutation.isLoading

  useEffect(() => {
    if (queryParamEmail) {
      form.setFieldsValue({
        email: queryParamEmail,
      })
      passwordInputRef.current?.focus()
    }
  }, [queryParamEmail])

  return (
    <UnauthenticatedPage pageTitle='Login'>
      <div style={{display: 'flex', justifyContent: 'space-between'}}>
        <Button
          icon={<GoogleOutlined />}
          disabled={isSigningIn}
          loading={signInWithGoogleMutation.isLoading}
          type='primary'
          onClick={() => signInWithGoogleMutation.mutate()}
        >
          Sign in with Google
        </Button>
        <Button
          icon={<LockOutlined />}
          disabled={isSigningIn}
          loading={signInWithSsoMutation.isLoading}
          onClick={() => signInWithSsoMutation.mutate()}
        >
          SSO
        </Button>
      </div>
      <Divider><Typography.Text type='secondary' italic>or sign in with email</Typography.Text></Divider>
      <Form
        layout='vertical'
        name='login_form'
        initialValues={{ remember: true }}
        onFinish={signInMutation.mutate}
        form={form}
        disabled={isSigningIn}
      >
        <Form.Item
          label='Email'
          name='email'
          required={false}
          rules={[
            {
              required: true,
              message: 'Email is required.',
              type: 'email',
            },
          ]}
        >
          <Input type='email' />
        </Form.Item>
        <Form.Item
          label='Password'
          name='password'
          required={false}
          rules={[
            {
              required: true,
              message: 'Password is required.',
            },
          ]}
        >
          <Input.Password ref={passwordInputRef} />
        </Form.Item>
        <Form.Item>
          <Form.Item name='remember' valuePropName='checked' noStyle>
            <Checkbox>Remember me</Checkbox>
          </Form.Item>
          <Button
            loading={signInMutation.isLoading}
            style={{ float: 'right' }}
            type='primary'
            htmlType='submit'
          >
            Sign in
          </Button>
        </Form.Item>
        <div style={{ display: 'flex', justifyContent: 'space-between' }}>
          <Link href='/register'>Register</Link>
          <Link href='/forgot-password'>Forgot your password?</Link>
        </div>
      </Form>
    </UnauthenticatedPage>
  )
}

Register Page

import React from 'react'
import {
  Button,
  Form,
  Input,
} from 'antd'
import Link from 'next/link'
import UnauthenticatedPage from '../components/layouts/UnauthenticatedPage'
import { useSignUpMutation } from '../components/Me/meHooks'

export default function App() {
  const signUpMutation = useSignUpMutation()

  return (
    <UnauthenticatedPage pageTitle='Register'>
      <Form
        layout='vertical'
        name='register_form'
        onFinish={signUpMutation.mutate}
        validateTrigger='onBlur'
      >
        <Form.Item
          label='Name'
          name='name'
          required={false}
          rules={[
            { required: true, message: 'Please enter your name.' },
          ]}
        >
          <Input />
        </Form.Item>
        <Form.Item
          label='Email'
          name='email'
          required={false}
          rules={[
            {
              required: true,
              message: 'Please enter your email.',
              type: 'email',
            },
          ]}
        >
          <Input type='email' />
        </Form.Item>
        <Form.Item
          style={{ marginBottom: '10px' }}
          label='Password'
          name='password'
          required={false}
          rules={[
            {
              required: true,
              message: 'Please enter your password.',
            },
          ]}
        >
          <Input.Password />
        </Form.Item>
        <Form.Item style={{ margin: '0' }}>
          <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
            <Button style={{ marginRight: '1rem' }}>
              <Link href='/'>Back to login</Link>
            </Button>
            <Button
              type='primary'
              disabled={signUpMutation.isLoading}
              loading={signUpMutation.isLoading}
              htmlType='submit'
              className='login-form-button'
            >
              Register
            </Button>
          </div>
        </Form.Item>
      </Form>
    </UnauthenticatedPage>
  )
}

Verify Page

import React, { useEffect } from 'react'
import {
  Button,
  Typography,
  Form,
  Input,
} from 'antd'
import { useRouter } from 'next/router'
import Link from 'next/link'
import UnauthenticatedPage from '../components/layouts/UnauthenticatedPage'
import { useVerifyAccountMutation } from '../components/Me/meHooks'

const { Title } = Typography

export default function VerifyPage() {
  const [form] = Form.useForm()
  const router = useRouter()
  const verifyAccountMutation = useVerifyAccountMutation()
  const queryParamEmail = (router.query.email as string) || ''
  const queryParamCode = (router.query.code as string) || ''

  useEffect(() => {
    if (queryParamEmail && queryParamCode) {
      verifyAccountMutation.mutate({ email: queryParamEmail, code: queryParamCode })
    }
    form.setFieldsValue({
      email: queryParamEmail,
      code: queryParamCode,
    })
  }, [queryParamEmail, queryParamCode])

  return (
    <UnauthenticatedPage pageTitle='Verify Account'>
      <Title level={3}>Verify your account</Title>
      {queryParamCode ? null : <p>Check your inbox for a verification email that includes a verification code, and enter it here. Alternatively, simply click the link in the email.</p>}
      <Form
        layout='vertical'
        name='verifyAccountForm'
        form={form}
        onFinish={verifyAccountMutation.mutate}
      >
        <Form.Item
          label='Email'
          name='email'
          required={false}
          rules={[
            {
              required: true,
              message: 'Email is required.',
              type: 'email',
            },
          ]}
        >
          <Input type='email' />
        </Form.Item>
        <Form.Item
          label='Verification Code'
          name='code'
          required={false}
          rules={[
            {
              required: true,
              message: 'Code is required.',
              max: 6,
            },
          ]}
        >
          <Input />
        </Form.Item>
        <Form.Item style={{ margin: '0' }}>
          <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
            <Button style={{ marginRight: '1rem' }}>
              <Link href='/'>Back to login</Link>
            </Button>
            <Button
              type='primary'
              disabled={verifyAccountMutation.isLoading}
              loading={verifyAccountMutation.isLoading}
              htmlType='submit'
              className='verify-account-form-button'
            >
              Verify Account
            </Button>
          </div>
        </Form.Item>
      </Form>
    </UnauthenticatedPage>
  )
}

Forgot Password Page

import React from 'react'
import {
  Button,
  Typography,
  Form,
  Input,
} from 'antd'
import Link from 'next/link'
import UnauthenticatedPage from '../components/layouts/UnauthenticatedPage'
import { useForgotPasswordMutation } from '../components/Me/meHooks'

const { Title } = Typography

export default function ForgotPassword() {
  const forgotPasswordMutation = useForgotPasswordMutation()

  return (
    <UnauthenticatedPage pageTitle='Forgot Password'>
      <Title level={3}>Forgot your password?</Title>
      <Form
        layout='vertical'
        name='forgotPasswordForm'
        onFinish={forgotPasswordMutation.mutate}
      >
        <Form.Item
          label='Email'
          name='email'
          required={false}
          rules={[
            {
              required: true,
              message: 'Please enter your email.',
              type: 'email',
            },
          ]}
        >
          <Input type='email' />
        </Form.Item>
        <Form.Item style={{ margin: '0' }}>
          <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
            <Button style={{ marginRight: '1rem' }}>
              <Link href='/'>Back to login</Link>
            </Button>
            <Button
              type='primary'
              disabled={forgotPasswordMutation.isLoading}
              loading={forgotPasswordMutation.isLoading}
              htmlType='submit'
              className='forgot-password-form-button'
            >
              Reset Password
            </Button>
          </div>
        </Form.Item>
      </Form>
    </UnauthenticatedPage>
  )
}

Reset Password Page

import React, { useEffect } from 'react'
import {
  Button,
  Typography,
  Form,
  Input,
} from 'antd'
import { useRouter } from 'next/router'
import Link from 'next/link'
import UnauthenticatedPage from '../components/layouts/UnauthenticatedPage'
import { useResetPasswordMutation } from '../components/Me/meHooks'

const { Title } = Typography

export default function RestPassword() {
  const [form] = Form.useForm()
  const router = useRouter()
  const queryParamEmail = (router.query.email as string) || ''
  useEffect(() => {
    form.setFieldsValue({
      email: queryParamEmail,
    })
  }, [queryParamEmail])
  const resetPasswordMutation = useResetPasswordMutation()

  return (
    <UnauthenticatedPage pageTitle='Reset Password'>
      <Title level={3}>Reset your password</Title>
      <Form
        layout='vertical'
        name='reset_password_form'
        form={form}
        onFinish={resetPasswordMutation.mutate}
      >
        <Form.Item
          label='Email'
          name='email'
          required={false}
          rules={[
            {
              required: true,
              message: 'Please enter your email.',
              type: 'email',
            },
          ]}
        >
          <Input type='email' />
        </Form.Item>
        <Form.Item
          label='Reset code'
          name='code'
          required={false}
          rules={[
            {
              required: true,
              message: 'Please enter your reset code.',
              max: 6,
            },
          ]}
        >
          <Input />
        </Form.Item>
        <Form.Item
          style={{ marginBottom: '10px' }}
          label='New Password'
          name='password'
          required={false}
          rules={[
            {
              required: true,
              message: 'Please enter your password.',
            },
          ]}
        >
          <Input.Password autoComplete='new-password' />
        </Form.Item>
        <Form.Item style={{ margin: '0' }}>
          <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
            <Button style={{ marginRight: '1rem' }}>
              <Link href='/'>Back to login</Link>
            </Button>
            <Button
              type='primary'
              disabled={resetPasswordMutation.isLoading}
              loading={resetPasswordMutation.isLoading}
              htmlType='submit'
              className='forgot-password-form-button'
            >
              Reset Password
            </Button>
          </div>
        </Form.Item>
      </Form>
    </UnauthenticatedPage>
  )
}

Hooks

'use client'

import axios from 'axios'
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import {
  confirmResetPassword,
  confirmSignUp,
  getCurrentUser,
  resetPassword,
  signIn,
  signInWithRedirect,
  signOut,
  signUp,
} from 'aws-amplify/auth'
import { useRouter } from 'next/router'
import { notification } from 'antd'

const api = {
  getMe: () => axios.get('/me'),
  updateMe: ({ data }) => axios.put('/me', { me: data }),
}

export function useCurrentUserQuery({ redirectOnNotAuth = true } = {}) {
  const router = useRouter()
  const currentUserQuery = useQuery(['currentUser'], async () => {
    try {
      const currentAuthenticatedUser = await getCurrentUser()
      return currentAuthenticatedUser
    } catch (error) {
      if (redirectOnNotAuth) {
        router.push('/')
      }
      return null
    }
  }, {
    retry: false,
  })
  return currentUserQuery
}

export function useSignInWithGoogleMutation() {
  const signInWithGoogleMutation = useMutation(() => {
    signInWithRedirect({ provider: 'Google' })
    return new Promise(() => null)
  },
  {
    onError: (err: Error) => {
      notification.error({
        message: 'Sign in with Google failed',
        description: err.message,
        placement: 'topRight',
      })
    },
  })

  return signInWithGoogleMutation
}

export function useSignInWithSsoMutation() {
  const signInWithSsoMutation = useMutation(() => {
    signInWithRedirect({
      provider: {
        custom: process.env.NEXT_PUBLIC_GoogleSamlIdpName!,
      },
    })
    return new Promise(() => null)
  },
  {
    onError: (err: Error) => {
      notification.error({
        message: 'Sign in with SSO failed',
        description: err.message,
        placement: 'topRight',
      })
    },
  })

  return signInWithSsoMutation
}

export function useSignInMutation() {
  const currentUserQuery = useCurrentUserQuery({ redirectOnNotAuth: false })
  const signInMutation = useMutation(async ({ email, password }: any) => {
    await signIn({ username: email, password })
    await currentUserQuery.refetch()
  },
  {
    onError: (err: Error) => {
      notification.error({
        message: 'Login failed',
        description: err.message,
        placement: 'topRight',
      })
    },
  })

  return signInMutation
}

export function useSignUpMutation() {
  const signInMutation = useSignInMutation()
  const router = useRouter()
  const signUpMutation = useMutation(async ({ name, password, email }: any) => {
    await signUp({
      username: email,
      password,
      options: {
        userAttributes: { email, name },
      },
    })

    if (process.env.NEXT_PUBLIC_AUTO_VERIFY_USERS) {
      await signInMutation.mutateAsync({ email, password })
      router.push('/posts')
      return
    }

    router.push(`/verify?email=${encodeURIComponent(email)}`)
  },
  {
    onError: async (err: Error) => notification.error({
      message: 'Error',
      description: err.message,
      placement: 'topRight',
    }),
  })

  return signUpMutation
}

export function useSignOutMutation({ includeEmailQueryStringParam = false } = {}) {
  const queryClient = useQueryClient()
  const currentUserQuery = useCurrentUserQuery({ redirectOnNotAuth: false })
  const signOutMutation = useMutation(async () => {
    try {
      await signOut({ global: true })
    } catch (error: any) {
      notification.error({
        message: 'Error trying to logout',
        description: error.message,
        placement: 'topRight',
      })
    } finally {
      queryClient.cancelQueries()
      queryClient.clear()
      queryClient.invalidateQueries()
      queryClient.removeQueries()
      window.localStorage.clear()
      const signInRoute = includeEmailQueryStringParam ? `/?${currentUserQuery.data?.username}` : '/'
      global.window.location.href = signInRoute
    }
  })

  return signOutMutation
}

export function useMeQuery({ isAuthenticated = true } = {}) {
  const meQuery = useQuery(['me'], async () => {
    const apiResponse = await api.getMe()
    return apiResponse.data
  }, { retry: false, enabled: isAuthenticated })
  return meQuery
}

export function useUpdateMeMutation() {
  const queryClient = useQueryClient()
  const updateMeMutation = useMutation<any, any, any>(async ({ userId, data }) => {
    try {
      const response = await api.updateMe({ data })

      await Promise.all([
        queryClient.invalidateQueries(['me']),
      ])

      return response
    } catch (error: any) {
      notification.error({
        message: 'Update failed',
        description: error?.response?.data?.message || error?.message || 'Unknown error',
        placement: 'topRight',
      })
    }
  })

  return updateMeMutation
}

export function useForgotPasswordMutation() {
  const router = useRouter()
  const forgotPasswordMutation = useMutation(
    async ({ email }: { email: string }) => {
      await resetPassword({ username: email })
      notification.success({
        message: 'Password reset link sent',
        description: 'Instructions have been sent to your email.',
        placement: 'topRight',
      })
      await router.push(`/reset-password?email=${email}`)
    },
    {
      onError: async (err: Error) => {
        notification.error({
          message: 'Forgot password failed',
          description: err.message,
          placement: 'topRight',
        })
      },
    },
  )

  return forgotPasswordMutation
}

export function useResetPasswordMutation() {
  const signInMutation = useSignInMutation()
  const router = useRouter()
  const resetPasswordMutation = useMutation(async ({ email, code, password }: { email: string, code: string, password: string }) => {
    await confirmResetPassword({
      username: email.trim(),
      confirmationCode: code.trim(),
      newPassword: password.trim(),
    })
    await signInMutation.mutateAsync({ email, password })
    router.push('/')
  },
  {
    onError: async (err: Error) => notification.error({
      message: 'Error resetting password',
      description: err.message,
      placement: 'topRight',
    }),
  })

  return resetPasswordMutation
}

export function useVerifyAccountMutation() {
  const router = useRouter()
  const verifyAccountMutation = useMutation(async ({ email, code }: { email: string, code: string }) => {
    await confirmSignUp({
      username: email.trim(),
      confirmationCode: code.trim(),
    })
    notification.success({
      message: 'Account confirmed! 🙌',
      description: 'You may now sign in.',
      placement: 'topRight',
    }),
    router.push(`/?email=${encodeURIComponent(email)}`)
  },
  {
    onError: async (err: Error) => notification.error({
      message: 'Error confirming account',
      description: err.message,
      placement: 'topRight',
    }),
  })

  return verifyAccountMutation
}

Custom Verify User Email

While not strictly part of the React implementation, we need to use a custom Verify User email so that we can link to the correct page and prefill the email and code. Modify the CDK from the first article in this series with this addCustomMessageTrigger method and Lambda Function:

export const handler = async (event, context) => {
  if (event.triggerSource === 'CustomMessage_SignUp') {
    return handleVerifyUserEmail(event)
  }

  return event
}

function handleVerifyUserEmail(event) {
  const { codeParameter, userAttributes } = event.request
  const verifyLink = `https://example.com/verify?email=${encodeURIComponent(userAttributes.email)}&code=${codeParameter}`

  const emailMessage = `<div style='text-align: center'>
  <p>Please verify your email address to complete account setup.</p>
  <p>Your verification code is</p>
  <h3>${codeParameter}</h3>
  <p>Navigate to <a href="${verifyLink}">${verifyLink}</a>.</p>
</div>`
  event.response.emailMessage = emailMessage
  event.response.emailSubject ='Verify your account ✅'

  return event
}

addCustomMessageTrigger() {
  // Custom message https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-message.html
  const { logRetentionInDays } = getEnvironmentConfig(this.node)
  const isSourceMapsEnabled = getIsSourceMapsEnabled({ node: this.node })
  const cognitoCustomMessageLogGroup = new LogGroup(this, 'CustomMessageLogGroup', {
    retention: logRetentionInDays,
  })
  const environment: StringMap = {}

  if (isSourceMapsEnabled) {
    environment.NODE_OPTIONS = '--enable-source-maps'
  }

  const cognitoCustomMessageFunction = new NodejsFunction(this, 'CustomMessageFunction', {
    runtime: Runtime.NODEJS_20_X,
    handler: 'handler',
    entry: path.join(cognitoPackageDir, 'cognito-custom-message.ts'),
    timeout: Duration.seconds(10),
    memorySize: 1024,
    logGroup: cognitoCustomMessageLogGroup,
    bundling: {
      sourceMap: isSourceMapsEnabled,
    },
    environment,
  })
  this.userPool.addTrigger(UserPoolOperation.CUSTOM_MESSAGE, cognitoCustomMessageFunction)
}

End

After reading this series of articles you should understand how a full stack identity solution with AWS Cognito User Pools works. If you haven't done so already, you can generate a full stack project with this solution and more with a single Code Genie command:

:::tip

npx @codegenie/cli generate --name "Todo" \
--idp 'Google' --idp 'SAML' \
--description "A todo list app that lets users create lists and add items to the list. Items should have a title, description, be markable as completed, have a due date, and have an image."

Code Genie generates a Full Stack AWS Serverless application based on your own data model, including a React (Next.js) Web App, Serverless Express REST API, DynamoDB Database, and Cognito Auth. :::

AWS Cognito User Pools: Create Resources with CDK

Sat, 02 Mar 2024 00:00:00 GMT

Pretty picture of the Login UI we build in the [React Cognito User Pools](/blog/aws-cognito-user-pools-add-auth-to-a-react-app) article.

Create Resources with CDK 👈 You are here
Sign in with Email, Google, or SAML and link to a single user
Add Auth to a React App

This article focuses on using CDK to create our Cognito User Pool resources as Infrastructure as Code (IAC). If you're already familiar with this you should consider moving onto the next part of this series Sign in with Email, Google, or SAML and link to a single user, since IAC can be a little lengthy (and boring).

:::tip The complete source code is available by generating a Code Genie app and specifying 'Google' and 'SAML' idp options:

npx @codegenie/cli generate --name "Todo" \
--idp 'Google' --idp 'SAML' \
--description "A todo list app that lets users create lists and add items to the list. Items should have a title, description, be markable as completed, have a due date, and have an image."

Code Genie generates a Full Stack AWS Serverless application based on your own data model, including a React (Next.js) Web App, Serverless Express REST API, DynamoDB Database, and Cognito Auth. :::

Cognito User Pool CDK (IAC)

Let's start with the basic setup of the Auth construct before we dive into the details defined in the class methods:

import { existsSync, readFileSync } from 'fs'
import path = require('path')
import { Aws, CfnOutput, Duration } from 'aws-cdk-lib'
import {
  ProviderAttribute,
  UserPool,
  UserPoolClient,
  UserPoolEmail,
  UserPoolIdentityProviderGoogle,
  UserPoolIdentityProviderSaml,
  UserPoolIdentityProviderSamlMetadata,
  UserPoolOperation,
} from 'aws-cdk-lib/aws-cognito'
import { Runtime } from 'aws-cdk-lib/aws-lambda'
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs'
import { Construct } from 'constructs'
import { Effect, PolicyStatement } from 'aws-cdk-lib/aws-iam'
import { ITable } from 'aws-cdk-lib/aws-dynamodb'
import { LogGroup } from 'aws-cdk-lib/aws-logs'
// These methods are responsible for getting environment-specific config (.e.g dev, staging, prod)
import {
  getEnvironmentConfig,
  getIsDeletionProtectionEnabled,
  getIsSourceMapsEnabled,
  getRemovalPolicy
} from '../environment-config'
import type { StringMap } from '../../../common/types'

// SAML-related variables
const GOOGLE_SAML_IDENTITY_PROVIDER_NAME = 'GoogleSaml'
const googleIDPMetadataPath = path.resolve(__dirname, '../../GoogleIDPMetadata.xml')
const googleIDPMetadataExists = existsSync(googleIDPMetadataPath)

// Cognito Lambda Functions path
const cognitoPackageDir = path.resolve(__dirname, '../../../cognito')

interface AuthProps {
  userTable: ITable
  webAppUrl: string
}

export default class Auth extends Construct {
  readonly userPool: UserPool
  readonly userPoolClient: UserPoolClient
  constructor(scope: Construct, id: string, props: AuthProps) {
    super(scope, id)

    this.userPool = this.createUserPool()
    this.userPoolClient = this.createUserPoolClient({ additionalOauthCallbackUrls: props.additionalOauthCallbackUrls })
    this.addDomainName()
    this.addTriggers({ userTable: props.userTable })
  }
  ...additional methods defined below
}

User Pool

  createUserPool() {
    const userPool = new UserPool(this, 'UserPool', {
      signInCaseSensitive: false,
      deletionProtection: getIsDeletionProtectionEnabled({ node: this.node }),
      removalPolicy: getRemovalPolicy({ node: this.node }),
      passwordPolicy: {
        minLength: 8,
      },
      selfSignUpEnabled: true,
      signInAliases: {
        username: false,
        email: true,
      },
    })

    new CfnOutput(this, 'UserPoolId', { key: 'UserPoolId', value: userPool.userPoolId })

    return userPool
  }

:::tip Always specify signInCaseSensitive: false. By default, User Pools treat usernames/emails as case sensitive, resulting in foo@bar.com and Foo@bar.com being treated as two separate users.

For production environments, specify deletionProtection: true and removalPolicy: cdk.RemovalPolicy.RETAIN to protect against accidentally deleting your User Pool (and users along with it). Here we are conditionally setting it based on environment, since we generally don't want/need protection in development environments. :::

User Pool Client

createUserPoolClient({ webAppUrl }: { webAppUrl: string }) {
  const environmentConfig = getEnvironmentConfig(this.node)
  const googleIdentityProvider = this.createGoogleIdentityProvider()
  const googleSamlIdentityProvider = this.createGoogleSamlIdentityProvider()
  const supportedIdentityProviders: {name: string}[] = []

  if (googleIdentityProvider) {
    supportedIdentityProviders.push({ name: googleIdentityProvider.providerName })
  }

  if (googleSamlIdentityProvider) {
    supportedIdentityProviders.push({ name: googleSamlIdentityProvider.providerName })
  }

  const callbackUrls = ['http://localhost:3001/']

  if (webAppUrl) {
    callbackUrls.push(webAppUrl)
  }

  const userPoolClient = this.userPool.addClient('UserPoolClient', {
    idTokenValidity: Duration.days(1),
    refreshTokenValidity: Duration.days(90),
    supportedIdentityProviders,
    oAuth: {
      callbackUrls: callbackUrls,
      logoutUrls: callbackUrls,
    },
  })

  if (googleIdentityProvider) {
    userPoolClient.node.addDependency(googleIdentityProvider)
  }

  if (googleSamlIdentityProvider) {
    userPoolClient.node.addDependency(googleSamlIdentityProvider)
  }

  new CfnOutput(this, 'UserPoolClientId', { key: 'UserPoolClientId', value: userPoolClient.userPoolClientId })

  return userPoolClient
}

We specify up to 2 OAuth callback URLs:

http://localhost:3001/ for local development. Consider removing this for production.
webAppUrl The live web app URL. In Code Genie, this is passed in as either the web app's custom domain name (if one is defined in cdk.json for the environment we're deploying) or the default Amplify Hosting URL.

Identity Providers

createGoogleIdentityProvider() {
  const { auth } = getEnvironmentConfig(this.node)

  if (!auth.googleClientId && !auth.googleClientId) return

  const googleIdentityProvider = new UserPoolIdentityProviderGoogle(this, 'GoogleIdp', {
    userPool: this.userPool,
    clientId: auth.googleClientId,
    clientSecret: auth.googleClientSecret,
    scopes: ['profile', 'email', 'openid'],
    attributeMapping: {
      email: ProviderAttribute.GOOGLE_EMAIL,
      fullname: ProviderAttribute.GOOGLE_NAME,
      familyName: ProviderAttribute.GOOGLE_FAMILY_NAME,
      givenName: ProviderAttribute.GOOGLE_GIVEN_NAME,
      profilePicture: ProviderAttribute.GOOGLE_PICTURE,
    },
  })
  new CfnOutput(this, 'GoogleIdpName', { key: 'GoogleIdpName', value: googleIdentityProvider.providerName })

  return googleIdentityProvider
}

Define the scopes and attributes from the External IDP that we want to store against our User in our User Pool. We're grabbing the profilePicture so that we can display the user's profile picture against their name.

:::tip Consider storing the Google Client Secret in AWS Secrets Manager and using the clientSecretValue prop instead. See the CDK Cognito User Pool Identity Provider docs for more details. :::

createGoogleSamlIdentityProvider() {
  if (!googleIDPMetadataExists) return null
  const googleIdpMetadataContents = readFileSync(googleIDPMetadataPath, 'utf-8')
  const userPoolIdentityProviderSamlMetadata = UserPoolIdentityProviderSamlMetadata.file(googleIdpMetadataContents)

  const googleSamlIdentityProvider = new UserPoolIdentityProviderSaml(this, 'GoogleSamlIdp', {
    name: GOOGLE_SAML_IDENTITY_PROVIDER_NAME,
    userPool: this.userPool,
    metadata: userPoolIdentityProviderSamlMetadata,
    attributeMapping: {
      email: ProviderAttribute.GOOGLE_EMAIL,
      fullname: ProviderAttribute.GOOGLE_NAME,
      familyName: ProviderAttribute.GOOGLE_FAMILY_NAME,
      givenName: ProviderAttribute.GOOGLE_GIVEN_NAME,
    },
  })
  new CfnOutput(this, 'GoogleSamlIdpName', { key: 'GoogleSamlIdpName', value: googleSamlIdentityProvider.providerName })

  return googleSamlIdentityProvider
}

There's a circular dependency between the Cognito User Pool and the SAML App you create in Google Workspace. Exit early if no GoogleIDPMetadata.xml file exists. When you create the SAML App, you'll need to provide the UserPoolRedirectUrlACS and UserPoolEntityId values from cdk-outputs.development.json. Download the SAML App's metadata file and redeploy your CDK Stack.

We must hardcode the SAML Identity Provider name (GOOGLE_SAML_IDENTITY_PROVIDER_NAME) to prevent a second circular dependency between the SAML Identity Provider and the PreSignup Cognito Trigger (which we'll meet soon). It doesn't seem like this should be a circular dependency since both resources are attached to the User Pool and the SAML Identity Provider has nothing to do with Triggers, but CDK will give you a "Circular dependency between resources" nonetheless.

Our attribute mappings for the SAML Identity Provider are similar to the Google Identity Provider. Unfortunately we don't have access to a profile picture, and even though we're requesting fullname here, Google doesn't allow you to map it when creating the SAML App. We'll handle this later.

Triggers

addTriggers({ userTable }: { userTable: ITable }) {
  this.addPreSignupTrigger()
  this.addPreTokenGenerationTrigger({  userTable  })
}

// Pre Signup https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-sign-up.html
addPreSignupTrigger() {
  const { auth, logRetentionInDays } = getEnvironmentConfig(this.node)
  const isSourceMapsEnabled = getIsSourceMapsEnabled({ node: this.node })

  const cognitoPreSignupLogGroup = new LogGroup(this, 'PreSignupLogGroup', {
    retention: logRetentionInDays,
  })

  const environment: StringMap = {}

  if (isSourceMapsEnabled) {
    environment.NODE_OPTIONS = '--enable-source-maps'
  }

  if (auth?.autoVerifyUsers) {
    environment.AUTO_VERIFY_USERS = '1'
  }

  environment.GOOGLE_SAML_IDENTITY_PROVIDER_NAME = GOOGLE_SAML_IDENTITY_PROVIDER_NAME

  const cognitoPreSignupFunction = new NodejsFunction(this, 'PreSignupFunction', {
    runtime: Runtime.NODEJS_20_X,
    handler: 'handler',
    entry: path.join(cognitoPackageDir, 'cognito-pre-signup.ts'),
    timeout: Duration.seconds(10),
    memorySize: 1024,
    logGroup: cognitoPreSignupLogGroup,
    bundling: {
      sourceMap: isSourceMapsEnabled,
    },
    environment,
  })
  const updateCognitoUserPoolPolicyStatement = new PolicyStatement({
    effect: Effect.ALLOW,
    actions: [
      'cognito-idp:AdminUpdateUserAttributes',
      'cognito-idp:AdminLinkProviderForUser',
      'cognito-idp:AdminCreateUser',
      'cognito-idp:AdminSetUserPassword',
      'cognito-idp:ListUsers',
    ],
    resources: [
      `arn:aws:cognito-idp:${Aws.REGION}:${Aws.ACCOUNT_ID}:userpool/*`,
    ],
  })
  cognitoPreSignupFunction.addToRolePolicy(updateCognitoUserPoolPolicyStatement)
  this.userPool.addTrigger(UserPoolOperation.PRE_SIGN_UP, cognitoPreSignupFunction)
}

Setting AUTO_VERIFY_USERS in development and testing environments is really convenient. It's just as convenient in production, but there are good reasons to require email confirmation (such as GDPR compliance).

We add our GOOGLE_SAML_IDENTITY_PROVIDER_NAME environment variable since we'll need that in the Lambda Function's code.

Our Lambda Function requires 5 permissions for the User Pool. Unfortunately we can't specify this.userPool.userPoolArn as the resource since CDK once again complains about a circular dependency. We're left with granting access to all User Pools within the same account and region.

addPreTokenGenerationTrigger({ userTable }: { userTable: ITable }) {
  // Pre Token Generation https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html
  const { logRetentionInDays } = getEnvironmentConfig(this.node)
  const isSourceMapsEnabled = getIsSourceMapsEnabled({ node: this.node })
  const cognitoPreTokenGenerationLogGroup = new LogGroup(this, 'PreTokenGenerationLogGroup', {
    retention: logRetentionInDays,
  })

  const environment: StringMap = {
    USER_TABLE: userTable.tableName,
  }

  if (isSourceMapsEnabled) {
    environment.NODE_OPTIONS = '--enable-source-maps'
  }

  const cognitoPreTokenGenerationFunction = new NodejsFunction(this, 'PreTokenGenerationFunction', {
    runtime: Runtime.NODEJS_20_X,
    handler: 'handler',
    entry: path.join(cognitoPackageDir, 'cognito-pre-token-generation.ts'),
    timeout: Duration.seconds(10),
    memorySize: 1024,
    logGroup: cognitoPreTokenGenerationLogGroup,
    bundling: {
      sourceMap: isSourceMapsEnabled,
    },
    environment,
  })

  // Give the Lambda function permission to read and write to DynamoDB
  const dynamoDBReadWritePolicy = new PolicyStatement({
    effect: Effect.ALLOW,
    actions: [
      'dynamodb:GetItem',
      'dynamodb:PutItem',
      'dynamodb:UpdateItem',
    ],
    resources: [
      userTable.tableArn,
    ],
  })
  cognitoPreTokenGenerationFunction.addToRolePolicy(dynamoDBReadWritePolicy)

  // Give the Lambda function permission to update Cognito User Attributes
  const updateCognitoUserPoolPolicyStatement = new PolicyStatement({
    effect: Effect.ALLOW,
    actions: [
      'cognito-idp:AdminUpdateUserAttributes',
    ],
    resources: [
      `arn:aws:cognito-idp:${Aws.REGION}:${Aws.ACCOUNT_ID}:userpool/*`,
    ],
  })
  cognitoPreTokenGenerationFunction.addToRolePolicy(updateCognitoUserPoolPolicyStatement)
  this.userPool.addTrigger(UserPoolOperation.PRE_TOKEN_GENERATION, cognitoPreTokenGenerationFunction)
}

:::tip You can create your own CDK Constructs to abstract away some of the repetitiveness you see in these Node.js Lambda Functions. :::

Environment Config

import * as cdk from 'aws-cdk-lib/core'
import type { Node } from 'constructs'

interface NodeEnvProps {
  node?: Node
  env?: string
}

export interface CdkJsonEnvironmentConfig {
  [environment: string]: CdkJsonEnvironmentConfigEnvironment
}
interface CdkJsonEnvironmentConfigEnvironment {
  profile: string
  region: string
  auth: CdkJsonEnvironmentConfigAuth
  logRetentionInDays: number
  email: CdkJsonEnvironmentConfigEmail
  api?: CdkJsonEnvironmentConfigApi
  ui?: CdkJsonEnvironmentConfigUi
  isSourceMapsEnabled?: boolean
}

interface CdkJsonEnvironmentConfigAuth {
  autoVerifyUsers?: boolean
  googleClientId?: string
  googleClientSecret?: string
}

interface CdkJsonEnvironmentConfigEmail {
  organizationInviteEmail: string
  verifyUserEmail?: string
  sandboxApprovedToEmails?: string[]
  verifiedDomain?: string
}

interface CdkJsonEnvironmentConfigApi {
  domainName: string
  validationDomain: string
}

interface CdkJsonEnvironmentConfigUi {
  domainName: string
}

export function getEnvironmentConfig(node: Node): CdkJsonEnvironmentConfigEnvironment {
  const env = getEnvironmentName(node)
  const environmentConfig = node.getContext('environmentConfig')[env]

  if (!environmentConfig) {
    throw new Error(`Missing environment config for ${env}`)
  }

  return environmentConfig
}

export function getEnvironmentName(node: Node) {
  return node.tryGetContext('env') || 'development'
}

export function getIsProd({
  node,
  env = node ? getEnvironmentName(node) : undefined,
}: NodeEnvProps) {
  return env === 'production'
}

export function getIsProdish({
  node,
  env = node ? getEnvironmentName(node) : undefined,
}: NodeEnvProps) {
  return ['staging', 'production'].includes(env)
}

export function getIsDev({
  node,
  env = node ? getEnvironmentName(node) : undefined,
}: NodeEnvProps) {
  return env === 'development'
}

// Source maps are extremely slow; don't run in prod
export function getIsSourceMapsEnabled({
  node,
}: { node: Node}) {
  const environmentConfig = getEnvironmentConfig(node)
  return environmentConfig.isSourceMapsEnabled ?? getIsDev({ node })
}

export function getIsPointInTimeRecoveryEnabled({
  node,
  env = node ? getEnvironmentName(node) : undefined,
}: NodeEnvProps) {
  return getIsProdish({ env })
}

export function getRemovalPolicy({
  node,
  env = node ? getEnvironmentName(node) : undefined,
}: NodeEnvProps) {
  // NOTE: During initial setup of staging and prod environments, it's beneficial to start with Deletion Protection off and
  // and Removal Policy set to Destroy. This way, if things go wrong during setup, it's easy to tear down and start again.
  // Once you have stable staging and production environments, remove these early return statements.
  return cdk.RemovalPolicy.DESTROY
  return getIsDev({ env }) ? cdk.RemovalPolicy.DESTROY : cdk.RemovalPolicy.RETAIN
}

export function getIsDeletionProtectionEnabled({
  node,
  env = node ? getEnvironmentName(node) : undefined,
}: NodeEnvProps) {
  return false
  return getIsProdish({ env })
}

The cdk.json looks like this:

{
  "app": "ts-node --prefer-ts-exts bin/cdk.ts",
  "context": {
    "environmentConfig": {
      "development": {...},
      "staging": {...},
      "production": {
        "auth": {
          "autoVerifyUsers": false,
          "googleClientId": "",
          "googleClientSecret": ""
        },
        "logRetentionInDays": 14,
        "ui": {
          "domainName": "app.example.com"
        }
      }
    }
  }
}

StringMap

export interface StringMap {
  [name: string]: string
}

Create External Identity Providers

Google Sign-in

Login to Google Cloud Console and select or create the relevant project.
Create OAuth client ID:
1. Select "Web application" as the "Application type" and enter a name
2. Click "Add URI" under "Authorised JavaScript origins". Copy the value for UserPoolRedirectUrlACS from cdk-outputs.dev.json and paste in only the domain part (i.e remove the '/saml2/idpresponse').
3. Click "Add URI" under "Authorised redirect URIs". Copy the same value from above, but this time add "/oauth2/idpresponse" to the end.
4. Click Save
Configure OAuth consent screen:
1. Select User Type "External" and mark it for "Production"
2. Under "Authorised domains" add "amazoncognito.com"
3. Save

Google SAML

Login to Google Workspace Admin and navigate to Apps => Web and Mobile Apps.
Click "Add app" => "Add custom SAML App". Enter a name for your app.
Download the metadata file to ./packages/cdk and click Continue.
From cdk-outputs.development.json, copy the values for UserPoolRedirectUrlACS and UserPoolEntityId and paste them into the respective fields in the Service Provider Details form and click Continue.
Add attribute mappings: Primary email => email; First name => first_name; Last name => family_name. Click Finish.
Click the User Access card; select "ON for everyone" and click Save.
Run npm run deploy:dev

End

Now that we've created our AWS Cognito User Pool and both External (Sign in with Google) and Internal (SAML) Google Apps, we're ready to move onto more interesting topics: Sign in with Email, Google, or SAML and link to a single user. This next article focuses on the Lambda Handler logic of the Lambda Functions we created with CDK.

:::tip The complete source code is available by generating a Code Genie app and specifying 'Google' and 'SAML' idp options:

npx @codegenie/cli generate --name "Todo" \
--idp 'Google' --idp 'SAML' \
--description "A todo list app that lets users create lists and add items to the list. Items should have a title, description, be markable as completed, have a due date, and have an image."

Code Genie generates a Full Stack AWS Serverless application based on your own data model, including a React (Next.js) Web App, Serverless Express REST API, DynamoDB Database, and Cognito Auth. :::

AWS Cognito User Pools: Sign in with Email, Google, or SAML and link to a single user

Sat, 02 Mar 2024 00:00:00 GMT

Pretty picture of the Login UI we build in the [React Cognito User Pools](/blog/aws-cognito-user-pools-add-auth-to-a-react-app) article.

Create Resources with CDK
Sign in with Email, Google, or SAML and link to a single user 👈 You are here
Add Auth to a React App

This article focuses on the logic behind the Cognito Triggers (Lambda Functions) that fire when users register or sign in. This solution allows users to sign in with multiple methods such as Email + Password, Google, and SAML, and have them all link to the same account within the app.

:::tip The complete source code is available by generating a Code Genie app and specifying 'Google' and 'SAML' idp options:

npx @codegenie/cli generate --name "Todo" \
--idp 'Google' --idp 'SAML' \
--description "A todo list app that lets users create lists and add items to the list. Items should have a title, description, be markable as completed, have a due date, and have an image."

Code Genie generates a Full Stack AWS Serverless application based on your own data model, including a React (Next.js) Web App, Serverless Express REST API, DynamoDB Database, and Cognito Auth. :::

:::note[Terminology] This example uses both Google Social Sign in, and Google SSO/SAML. So that we don't confuse the two, I'll just refer to the latter as the "SAML" Identity Provider (IDP) going forward. The terms "Federated" and "External" are used interchangeably. :::

Cognito Triggers

The core of this solution relies on two Cognito Triggers. The high-level flow looks like this:

The Pre sign-up Trigger fires when a user signs up using Google, SAML, or Email + Password. It's also triggered when an existing user signs in using a new external identity for the first time (e.g. if a user signs up using SAML and then later signs in using Google SSO with the same email).
1. If they're signing up with Email + Password, continue.
2. If they're signing up via Google or SAML and they haven't already signed up using a different method with the same email: a native Cognito User is created for that email.
3. The External Identity is linked to the native Cognito User for that email.
The Pre token generation Trigger fires on every sign in.
1. If this is their first time signing in, a User record is created in DynamoDB.
2. If the user has External Identities linked to their account, the account is marked as verified.

We'll first look at the code for each trigger and then discuss the details.

Pre Sign-up Lambda Handler

import { randomBytes } from 'crypto'
import {
  AdminCreateUserCommand,
  AdminLinkProviderForUserCommand,
  AdminSetUserPasswordCommand,
  CognitoIdentityProviderClient,
  ListUsersCommand,
  MessageActionType,
} from '@aws-sdk/client-cognito-identity-provider'
import type { PreSignUpTriggerEvent } from 'aws-lambda'
import UnsupportedIdentityProviderNameException from './exceptions/UnsupportedIdentityProviderNameException'
import getFullName from './getFullName'

const providerNamesLowerCaseLookup = {
  'google': 'Google',
  // 'facebook': 'Facebook',
}

// Env vars are passed in via CDK defined in the previous article
const { AUTO_VERIFY_USERS, GOOGLE_SAML_IDENTITY_PROVIDER_NAME } = process.env

if (GOOGLE_SAML_IDENTITY_PROVIDER_NAME) {
  providerNamesLowerCaseLookup[GOOGLE_SAML_IDENTITY_PROVIDER_NAME.toLowerCase()] = GOOGLE_SAML_IDENTITY_PROVIDER_NAME
}

const cognitoIdpClient = new CognitoIdentityProviderClient({ region: 'us-west-2' })

export async function handler (event: PreSignUpTriggerEvent) {
  switch(event.triggerSource) {
  case 'PreSignUp_ExternalProvider':
    await handleExternalProvider({ event })
    break
  case 'PreSignUp_SignUp':
  case 'PreSignUp_AdminCreateUser':
    if (AUTO_VERIFY_USERS) {
      event.response.autoConfirmUser = true
      event.response.autoVerifyEmail = true
    }
  }

  return event
}

async function handleExternalProvider({ event }: { event: PreSignUpTriggerEvent }) {
  const {
    userName,
    userPoolId,
    request: {
      userAttributes,
    },
  } = event

  const { email, name, given_name: givenName, family_name: familyName } = userAttributes
  const [providerName, providerUserId] = userName.split('_')
  const providerNameWithCorrectCapitalization = providerNamesLowerCaseLookup[providerName.toLowerCase()]

  if (!providerNameWithCorrectCapitalization) {
    throw new UnsupportedIdentityProviderNameException({ providerName, validIdentityProviderNamesMap: providerNamesLowerCaseLookup })
  }

  const cognitoUsersWithEmail = await listCognitoUsersWithEmail({ userPoolId, email })

  if (cognitoUsersWithEmail.Users?.length) {
    const cognitoUsername = cognitoUsersWithEmail.Users[0].Username || 'username-not-found'

    await linkCognitoUserAccounts({ cognitoUsername, userPoolId, providerName: providerNameWithCorrectCapitalization, providerUserId })
  } else {
    const newNativeCognitoUser = await createCognitoUser({ userPoolId, email, givenName, familyName, name })

    const newNativeCognitoUserUsername = newNativeCognitoUser.User?.Username || 'username-not-found'

    await linkCognitoUserAccounts({ cognitoUsername: newNativeCognitoUserUsername, userPoolId, providerName: providerNameWithCorrectCapitalization, providerUserId })
  }

  return event
}

function listCognitoUsersWithEmail ({ userPoolId, email }) {
  return cognitoIdpClient.send(new ListUsersCommand({
    UserPoolId: userPoolId,
    Filter: `email = '${email}'`,
  }))
}

function linkCognitoUserAccounts ({ cognitoUsername, userPoolId, providerName, providerUserId }) {
  return cognitoIdpClient.send(new AdminLinkProviderForUserCommand({
    SourceUser: {
      ProviderName: providerName,
      ProviderAttributeName: 'Cognito_Subject',
      ProviderAttributeValue: providerUserId,
    },
    DestinationUser: {
      ProviderName: 'Cognito',
      ProviderAttributeValue: cognitoUsername,
    },
    UserPoolId: userPoolId,
  }))
}

async function createCognitoUser ({ userPoolId, email, givenName, familyName, name }) {
  const fullName = getFullName({ name, givenName, familyName })
  const createdCognitoUser = await cognitoIdpClient.send(new AdminCreateUserCommand({
    UserPoolId: userPoolId,
    // Don't send an email with the temporary password
    MessageAction: MessageActionType.SUPPRESS,
    Username: email,
    UserAttributes: [
      {
        Name: 'name',
        Value: fullName,
      },
      {
        Name: 'email',
        Value: email,
      },
      {
        Name: 'email_verified',
        Value: 'true',
      },
    ],
  }))

  // Set password to confirm user; AdminConfirmSignUp doesn't work on manually created users
  await setCognitoUserPassword({ userPoolId, email })

  return createdCognitoUser
}

function setCognitoUserPassword ({ userPoolId, email }) {
  const password = randomBytes(16).toString('hex')

  return cognitoIdpClient.send(new AdminSetUserPasswordCommand({
    Password: password,
    UserPoolId: userPoolId,
    Username: email,
    Permanent: true,
  }))
}

This handler starts by checking the event.triggerSource to determine if the signup is from an External Identity Provider (e.g. Google) or if it's with Email + Password. If the signup is with Email + Password and the AUTO_VERIFY_USERS environment variable is set, the account is automatically verified and confirmed. The user doesn't receive a verification email and is instantly signed in, reducing friction during the critical user registration flow.

:::caution There are good reasons to require email confirmation (such as GDPR compliance). It's advised to only auto-verify in development/preview environments (Code Genie projects are configured this way out-of-the-box) :::

If the signup is from an External IDP we first get the provider name from the event.userName property. This property's value looks like 'google_108986458847054040795', so we split on '_' to get the providerName and providerUserId (the user's ID within the External IDP). We then lookup providerName in the providerNamesLowerCaseLookup map to get the correct capitalization required by Cognito's adminLinkProviderForUser API. If no matching provider is found within the map, we throw an error.

:::note This is an unfortunate extra step we're forced to do and it would be great if the Cognito Trigger included the correct capitliazation of the provider name for us.

Every other resource that I found on this topic suggests simply uppercasing the first character in providerName. This doesn't work if you have a SAML/OIDC provider and specify a name like 'GoogleSaml' (which is what we named it in our previous article). :::

Next we query Cognito for an existing account under that Email, and if one exists we simply link the External IDP account to it. Otherwise, we create a native Cognito User with a random password and then link the External IDP account.

:::note This approach handles both scenarios where:

a user first registers with Email + Password and later signs in with Google/SAML
a user first registers with Google/SAML and later signs in with Email + Password

Cognito doesn't support linking an Email + Password account to an "External" account. By first creating a native Cognito account in scenario 2, we enable the user to login with their email address in the future. Ideally, the user would be able to go through the normal Register with Email + Password flow and things would "just work". Unfortunately, they must use the Forgot Password flow to reset their password before they can sign in with this method. :::

Pre Token Generation Lambda Handler

import { AdminUpdateUserAttributesCommand, CognitoIdentityProviderClient } from '@aws-sdk/client-cognito-identity-provider'
import axios from 'axios'
import type { PreTokenGenerationTriggerEvent } from 'aws-lambda'
import { createUser, getUser, updateUser } from '../api/controllers/user'
import getFullName from './getFullName'

const cognitoIdpClient = new CognitoIdentityProviderClient({ region: 'us-west-2' })

interface Identity {
  providerType: 'Google' | 'Facebook' | 'SAML' | 'OIDC' | string
}

export async function handler (event: PreTokenGenerationTriggerEvent) {
  const {
    userPoolId,
    userName,
    request: {
      userAttributes,
    },
  } = event
  // Don't await here so that we can run the Dynamo and Cognito operations in parallel
  const syncUserToDynamoPromise = syncUserToDynamo(userAttributes)
  let setUserEmailVerifiedTruePromise

  const { identities, email } = userAttributes

  if (email && identities) {
    const identitiesArray: Identity[] = JSON.parse(identities)
    const hasExternalIdentity = identitiesArray.some(identity => ['Google', 'Facebook', 'SAML', 'OIDC'].includes(identity.providerType))

    if (hasExternalIdentity) {
      // Cognito has a "feature" that sets all attributes to their default values when not present on the external identity provider.
      // This results in the email_verified being set to false on each login, which causes features like forgot password to not work.
      // Force it back to email_verified=true.
      setUserEmailVerifiedTruePromise = setUserEmailVerifiedTrue({ userPoolId, username: userName })
    }
  }

  await Promise.all([syncUserToDynamoPromise, setUserEmailVerifiedTruePromise])

  return event
}

async function setUserEmailVerifiedTrue ({ userPoolId, username }) {
  return cognitoIdpClient.send(new AdminUpdateUserAttributesCommand({
    UserPoolId: userPoolId,
    Username: username,
    UserAttributes: [{Name: 'email_verified', Value: 'true'}],
  }))
}

async function syncUserToDynamo (userAttributes) {
  const {
    sub: userId,
    email,
    given_name: givenName,
    family_name: familyName,
    name,
    picture,
  } = userAttributes

  const fullName = getFullName({ name, givenName, familyName })
  const existingUser = await getUser({ userId })

  if (existingUser) {
    // If the user doesn't have an avatar set and one is available from the external IDP: set it to the user's avatar
    // NOTE: Uploading user avatar to S3 instead of storing the base64 in DynamoDB is a better solution.
    if (picture && !existingUser.data.avatar) {
      const base64EncodedProfilePicture = await fetchAndBase64EncodeImage(picture)
      await updateUser({ userId, user: { avatar: base64EncodedProfilePicture }})
    }
    return
  }

  const user: any = {
    name: fullName,
    email,
  }

  if (picture) {
    const base64EncodedProfilePicture = await fetchAndBase64EncodeImage(picture)

    if (base64EncodedProfilePicture) {
      user.avatar = base64EncodedProfilePicture
    }
  }

  return createUser({ userId, user })
}

async function fetchAndBase64EncodeImage(imageUrl) {
  try {
    const image = await axios.get(imageUrl, {responseType: 'arraybuffer'})
    const base64 = Buffer.from(image.data).toString('base64')
    return base64 ? `data:image/png;base64, ${base64}` : null
  } catch(error: unknown) {
    // If we encounter an error while fetching/encoding the image, it's better to just log and continue.
    // The user won't have their profile picture, but at least they'll be registered/logged in!
    console.error('cognito.preTokenGeneration.syncUserToDynamo.fetchAndBase64EncodeImage.error', {
      errorName: (error as Error).name,
      errorMessage: (error as Error).message,
    })
  }
}

This handler's primary purposes are to create a user record in DynamoDB if one doesn't exist (syncUserToDynamo), and to ensure the Cognito user remains verified (setUserEmailVerifiedTrue). Both operations are executed in parallel to improve performance thanks to our await Promise.all.

syncUserToDynamo queries DynamoDB for a User item with the Cognito User's ID (event.request.userAttributes.sub), and if one doesn't exist it's inserted into DynamoDB. If a user already exists but doesn't have a profile picture set and one is available through the sign in method they're using, it updates DynamoDB with the profile picture (this happens when they first signed in with Email or SAML which doesn't expose a profile picture, and then signed in with Google). You could also choose to sync other data here, e.g. if you want to update the user's name or other data to match what's in the External IDP.

:::tip It's recommended to store User data in DynamoDB, and let Cognito just handle the auth. Consider storing the profile picture in S3 instead. :::

If the Cognito User has External Identities linked to it, setUserEmailVerifiedTrue is called to force the email_verified attribute back to true. There is an unfortunate Cognito "feature" that sets all User attributes to their default value when signing in with an External IDP that doesn't return that value. For email_verified this is false. We must keep email_verified=true, otherwise the user won't be able to sign in with their Email + Password or use the "Forgot Password" flow.

:::note The createUser, getUser, updateUser functions are just wrappers around a DynamoDB Toolbox Entity. :::

getFullName

A small helper function for getting the user's full name from the External IDP when it doesn't support mapping one.

// Google SAML doesn't allow mapping the full name field, so we instead must construct this ourselves based on Given Name and Family Name.
export default function getFullName({ name, givenName, familyName}) {
  let fullName = name

  // If the name is JUST the given name, AND a family name exists: concatenate them into full name.
  // This is especially useful in Google SAML where it doesn't include a full name attribute.
  if (givenName && familyName && (!fullName || fullName === givenName)) {
    fullName = `${givenName} ${familyName}`
  } else if (!fullName) {
    fullName = givenName || familyName
  }

  return fullName
}

End

Ideally, multi-account linking between External Identity Providers and native Cognito Users would be built into Cognito, but thanks to the power of Lambda Triggers it's something we're able to implement ourselves.

If you want to build a full stack AWS application that includes functionality like this and much more out of the box, you should try Code Genie 🧞‍♂️

:::tip The complete source code is available by generating a Code Genie app and specifying 'Google' and 'SAML' idp options:

npx @codegenie/cli generate --name "Todo" \
--idp 'Google' --idp 'SAML' \
--description "A todo list app that lets users create lists and add items to the list. Items should have a title, description, be markable as completed, have a due date, and have an image."

Code Genie generates a Full Stack AWS Serverless application based on your own data model, including a React (Next.js) Web App, Serverless Express REST API, DynamoDB Database, and Cognito Auth. :::

Introducing Code Genie 🧞‍♂️

Wed, 31 Jan 2024 00:00:00 GMT

Today we're excited to launch Code Genie -- the FASTEST way to build software! 🚀

With a single ~~AI-powered command~~ wish 🧞‍♂️, Code Genie generates a custom Full Stack Serverless AWS Application based on your description. In under a minute! Try it out for yourself:

npx @codegenie/cli generate --name "Wildlife Rescue" \
--description "An app that lets users upload photos, location, time, species and other information so that Wildlife Rescuers can get notified and respond to reports of injured wildlife in their area."

:::tip[Deploy 🚀] You can include the --deploy flag to instantly deploy to AWS, or you can run npm run init:dev within the project directory after it's generated. :::

Projects include:

A Next.js Web App hosted on AWS Amplify Hosting
Serverless Express REST API on Lambda and API Gateway
DynamoDB Database
Cognito User Pools for Auth
CDK for all AWS infrastructure
Local Development
Multi-environment support (dev, staging, production)
Custom domain names for Web App and API
Custom Emails
CI/CD via GitHub Actions (WIP)
Much more (and even more to come)

We can't wait to see what you build! Join us on Discord, and follow us on Twitter and LinkedIn for support and announcements.