Email Notifications [mimics main branch]

infra/app/app-config/dev.tf

@@ -9,6 +9,7 @@ module "dev_config" {
   enable_https                    = true
   has_database                    = local.has_database
   has_incident_management_service = local.has_incident_management_service
+  enable_notifications            = local.enable_notifications
 
   # Enable and configure identity provider.
   enable_identity_provider = local.enable_identity_provider

infra/app/app-config/env-config/notifications.tf

@@ -1,16 +1,31 @@
 # Notifications configuration
 locals {
   notifications_config = var.enable_notifications ? {
-    # Set to an SES-verified email address to be used when sending emails.
-    # Docs: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-email.html
-    sender_email = null
+    # Pinpoint app name.
+    name = "${var.app_name}-${var.environment}"
+
+    # The method to use to verify the sender email address.
+    # - Must be 'email' or 'domain'.
+    # - If method is 'email', AWS will send you an email with a one-time link. Click on
+    #   the link to verify the email address.
+    # - If method is 'domain', then custom domains are required and the domain used will
+    #   match the one set in the env-config. See /docs/infra/set-up-custom-domains.md
+    # Docs: https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-manage-verify.html
+    email_verification_method = "domain"
 
     # Configure the name that users see in the "From" section of their inbox, so that it's
     # clearer who the email is from.
-    sender_display_name = null
+    sender_display_name = "coilysiren"
+
+    # Set to the email address to be used when sending emails.
+    # - If enable_notifications is true, this is required.
+    # - If email_verification_method is set to 'domain', make sure the domain name of the
+    #   sender_email matches the domain provided in the env-config.
+    # Docs: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-email.html
+    sender_email = "[email protected]"
 
     # Configure the REPLY-TO email address if it should be different from the sender.
     # Note: Only used by the identity-provider service.
-    reply_to_email = null
+    reply_to_email = "[email protected]"
   } : null
 }

infra/app/app-config/main.tf

@@ -31,9 +31,10 @@ locals {
   enable_identity_provider = true
 
   # Whether or not the application should deploy a notification service
-  # Note: This is not yet ready for use.
-  # TODO(https://github.com/navapbc/template-infra/issues/567)
-  enable_notifications = false
+  # If enabled:
+  # 1. Creates an AWS Pinpoint application
+  # 2. Configures email notifications using AWS SES
+  enable_notifications = true
 
   environment_configs = {
     dev     = module.dev_config

infra/app/app-config/outputs.tf

@@ -34,6 +34,10 @@ output "enable_identity_provider" {
   value = local.enable_identity_provider
 }
 
+output "enable_notifications" {
+  value = local.enable_notifications
+}
+
 output "shared_network_name" {
   value = local.shared_network_name
 }

infra/app/app-config/prod.tf

@@ -10,6 +10,7 @@ module "prod_config" {
   has_database                    = local.has_database
   has_incident_management_service = local.has_incident_management_service
   enable_identity_provider        = local.enable_identity_provider
+  enable_notifications            = local.enable_notifications
 
   # These numbers are a starting point based on this article
   # Update the desired instance size and counts based on the project's specific needs

infra/app/app-config/staging.tf

@@ -10,6 +10,7 @@ module "staging_config" {
   has_database                    = local.has_database
   has_incident_management_service = local.has_incident_management_service
   enable_identity_provider        = local.enable_identity_provider
+  enable_notifications            = local.enable_notifications
 
   # Enables ECS Exec access for debugging or jump access.
   # See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html

infra/app/service/main.tf

@@ -51,6 +51,30 @@ locals {
 
   network_config = module.project_config.network_configs[local.environment_config.network_name]
 
+  # Notifications locals.
+  #
+  # 1. If notifications are enabled and the verification method is 'email', then we
+  #   extract the domain_name from the sender_email. For example:
+  #   example.com from sender_email: [email protected]
+  #
+  # 2. If notifications are enabled and the verification method is 'domain', then we
+  #   construct the domain_name using the format: <terraform workspace><environment.<domain>
+  #   For example: t-123456-dev.bar.com
+
+  mail_from_domain = "mail.${local.notifications_sender_email_domain_name}"
+
+  notifications_sender_email_domain_name = module.app_config.enable_notifications ? (
+    local.notifications_config.email_verification_method == "email" ?
+    regex("@(.*)", local.notifications_config.sender_email)[0] :
+    "${local.prefix}${var.environment_name}.${local.service_config.domain_name}"
+  ) : null
+
+  notifications_sender_email = module.app_config.enable_notifications ? (
+    local.notifications_config.email_verification_method == "email" ?
+    local.notifications_config.sender_email :
+    "${regex("(.*)@", local.notifications_config.sender_email)[0]}@${local.notifications_sender_email_domain_name}"
+  ) : null
+
   # Identity provider locals.
   # If this is a temporary environment, re-use an existing Cognito user pool.
   # Otherwise, create a new one.
@@ -233,6 +257,29 @@ module "storage" {
   is_temporary = local.is_temporary
 }
 
+module "email_identity" {
+  count  = module.app_config.enable_notifications ? 1 : 0
+  source = "../../modules/email-identity"
+
+  email_verification_method = local.notifications_config.email_verification_method
+  name                      = local.notifications_config.name
+  sender_email              = local.notifications_sender_email
+  mail_from_domain          = local.mail_from_domain
+  domain_name               = local.notifications_sender_email_domain_name
+}
+
+module "notifications" {
+  count  = module.app_config.enable_notifications ? 1 : 0
+  source = "../../modules/notifications"
+
+  email_configuration_set_name = module.email_identity[0].email_configuration_set_name
+  email_identity_arn           = module.email_identity[0].email_identity_arn
+
+  name                = "${local.prefix}${local.notifications_config.name}"
+  sender_display_name = local.notifications_config.sender_display_name
+  sender_email        = local.notifications_sender_email
+}
+
 # If the app has `enable_identity_provider` set to true AND this is not a temporary
 # environment, then create a new identity provider.
 module "identity_provider" {
@@ -247,9 +294,12 @@ module "identity_provider" {
   verification_email_message       = local.identity_provider_config.verification_email.verification_email_message
   verification_email_subject       = local.identity_provider_config.verification_email.verification_email_subject
 
-  sender_email        = local.notifications_config == null ? null : local.notifications_config.sender_email
-  sender_display_name = local.notifications_config == null ? null : local.notifications_config.sender_display_name
-  reply_to_email      = local.notifications_config == null ? null : local.notifications_config.reply_to_email
+  sender_email        = module.app_config.enable_notifications ? local.notifications_sender_email : null
+  sender_display_name = module.app_config.enable_notifications ? local.notifications_config.sender_display_name : null
+  reply_to_email      = module.app_config.enable_notifications ? local.notifications_config.reply_to_email : null
+
+  # This requires an email identity that has been verified for sending.
+  email_identity_arn = module.app_config.enable_notifications ? module.email_identity[0].verified_email_identity_arn : null
 }
 
 # If the app has `enable_identity_provider` set to true AND this *is* a temporary

infra/modules/email-identity/logs.tf

@@ -0,0 +1,23 @@
+# Configures AWS SES to send additional logging to AWS Cloudwatch.
+# See https://docs.aws.amazon.com/ses/latest/dg/event-destinations-manage.html
+resource "aws_ses_event_destination" "logs" {
+  name                   = "${var.name}-email-identity-logs"
+  configuration_set_name = aws_sesv2_configuration_set.email.configuration_set_name
+  enabled                = true
+  matching_types = [
+    "bounce",
+    "click",
+    "complaint",
+    "delivery",
+    "open",
+    "reject",
+    "renderingFailure",
+    "send"
+  ]
+
+  cloudwatch_destination {
+    dimension_name = "email_type"
+    default_value  = "other"
+    value_source   = "messageTag"
+  }
+}

infra/modules/email-identity/main.tf

@@ -0,0 +1,131 @@
+# This module manages an SESv2 email identity.
+data "aws_caller_identity" "current" {}
+data "aws_region" "current" {}
+
+locals {
+  stripped_domain_name      = replace(var.domain_name, "/[.]$/", "")
+  stripped_mail_from_domain = replace(var.mail_from_domain, "/[.]$/", "")
+  dash_domain               = replace(var.domain_name, ".", "-")
+}
+
+# Verify email sender identity.
+# Docs: https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-email-manage-verify.html
+resource "aws_sesv2_email_identity" "sender" {
+  email_identity         = var.email_verification_method == "email" ? var.sender_email : local.stripped_domain_name
+  configuration_set_name = aws_sesv2_configuration_set.email.configuration_set_name
+}
+
+# The configuration set applied to messages that is sent through this email channel.
+resource "aws_sesv2_configuration_set" "email" {
+  configuration_set_name = var.name
+
+  delivery_options {
+    tls_policy = "REQUIRE"
+  }
+
+  reputation_options {
+    reputation_metrics_enabled = true
+  }
+
+  sending_options {
+    sending_enabled = true
+  }
+
+  suppression_options {
+    suppressed_reasons = ["BOUNCE", "COMPLAINT"]
+  }
+}
+
+# Allow AWS Pinpoint to send email on behalf of this email identity.
+# Docs: https://docs.aws.amazon.com/pinpoint/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_resource-based-policy-examples-access-ses-identities
+resource "aws_sesv2_email_identity_policy" "sender" {
+  email_identity = aws_sesv2_email_identity.sender.email_identity
+  policy_name    = "PinpointEmail"
+
+  policy = jsonencode(
+    {
+      Version = "2008-10-17",
+      Statement = [
+        {
+          Sid    = "PinpointEmail",
+          Effect = "Allow",
+          Principal = {
+            Service = "pinpoint.amazonaws.com"
+          },
+          Action   = "ses:*",
+          Resource = "${aws_sesv2_email_identity.sender.arn}",
+          Condition = {
+            StringEquals = {
+              "aws:SourceAccount" = "${data.aws_caller_identity.current.account_id}"
+            },
+            StringLike = {
+              "aws:SourceArn" = "arn:aws:mobiletargeting:${data.aws_region.current.name}:${data.aws_caller_identity.current.account_id}:apps/*"
+            }
+          }
+        }
+      ]
+    }
+  )
+}
+
+# If email_verification_method is "domain", create a Route53 hosted zone for the sending
+# domain.
+resource "aws_route53_zone" "zone" {
+  count = var.email_verification_method == "domain" ? 1 : 0
+  name  = var.domain_name
+  # checkov:skip=CKV2_AWS_38:TODO(https://github.com/navapbc/template-infra/issues/560) enable DNSSEC
+}
+
+resource "aws_sesv2_email_identity_mail_from_attributes" "sender" {
+  email_identity   = aws_sesv2_email_identity.sender.email_identity
+  mail_from_domain = local.stripped_mail_from_domain
+
+  depends_on = [aws_sesv2_email_identity.sender]
+}
+
+# DNS records for email identity verification if email_verification_method is "domain"
+resource "aws_route53_record" "dkim" {
+  count = var.email_verification_method == "domain" ? 3 : 0
+
+  allow_overwrite = true
+  ttl             = 60
+  type            = "CNAME"
+  zone_id         = aws_route53_zone.zone[0].zone_id
+  name            = "${aws_sesv2_email_identity.sender.dkim_signing_attributes[0].tokens[count.index]}._domainkey"
+  records         = ["${aws_sesv2_email_identity.sender.dkim_signing_attributes[0].tokens[count.index]}.dkim.amazonses.com"]
+
+  depends_on = [aws_sesv2_email_identity.sender]
+}
+
+resource "aws_route53_record" "spf_mail_from" {
+  count = var.email_verification_method == "domain" ? 1 : 0
+
+  allow_overwrite = true
+  ttl             = "600"
+  type            = "TXT"
+  zone_id         = aws_route53_zone.zone[0].zone_id
+  name            = aws_sesv2_email_identity_mail_from_attributes.sender.mail_from_domain
+  records         = ["v=spf1 include:amazonses.com ~all"]
+}
+
+resource "aws_route53_record" "mx_send_mail_from" {
+  count = var.email_verification_method == "domain" ? 1 : 0
+
+  allow_overwrite = true
+  type            = "MX"
+  ttl             = "600"
+  zone_id         = aws_route53_zone.zone[0].zone_id
+  name            = aws_sesv2_email_identity_mail_from_attributes.sender.mail_from_domain
+  records         = ["10 feedback-smtp.${data.aws_region.current.name}.amazonses.com"]
+}
+
+resource "aws_route53_record" "mx_receive" {
+  count = var.email_verification_method == "domain" ? 1 : 0
+
+  allow_overwrite = true
+  type            = "MX"
+  ttl             = "600"
+  name            = var.mail_from_domain
+  zone_id         = aws_route53_zone.zone[0].zone_id
+  records         = ["10 inbound-smtp.${data.aws_region.current.name}.amazonaws.com"]
+}

infra/modules/email-identity/outputs.tf

@@ -0,0 +1,11 @@
+output "email_configuration_set_name" {
+  value = aws_sesv2_configuration_set.email.configuration_set_name
+}
+
+output "email_identity_arn" {
+  value = aws_sesv2_email_identity.sender.arn
+}
+
+output "verified_email_identity_arn" {
+  value = aws_sesv2_email_identity.sender.verified_for_sending_status ? aws_sesv2_email_identity.sender.arn : null
+}

infra/modules/email-identity/variables.tf

@@ -0,0 +1,29 @@
+variable "email_verification_method" {
+  type        = string
+  description = "The method to use to verify the sender email address"
+  default     = "email"
+  validation {
+    condition     = can(regex("^(email|domain)$", var.email_verification_method))
+    error_message = "email_verification_method must be either 'email' or 'domain'"
+  }
+}
+
+variable "name" {
+  type        = string
+  description = "Name of the notifications project/application"
+}
+
+variable "sender_email" {
+  type        = string
+  description = "Email address to use to send notification emails"
+}
+
+variable "domain_name" {
+  description = "The domain name to configure SES."
+  type        = string
+}
+
+variable "mail_from_domain" {
+  type        = string
+  description = "Subdomain (of the route53 zone) which is to be used as MAIL FROM address"
+}

infra/modules/identity-provider/resources/main.tf

@@ -4,11 +4,6 @@
 ## - Configures MFA
 ############################################################################################
 
-data "aws_ses_email_identity" "sender" {
-  count = var.sender_email != null ? 1 : 0
-  email = var.sender_email
-}
-
 resource "aws_cognito_user_pool" "main" {
   name = var.name
 
@@ -34,12 +29,12 @@ resource "aws_cognito_user_pool" "main" {
     # Use this SES email to send cognito emails. If we're not using SES for emails then use null.
     # Optionally configures the FROM address and the REPLY-TO address.
     # Optionally configures using the Cognito default email or using SES.
-    source_arn            = var.sender_email != null ? data.aws_ses_email_identity.sender[0].arn : null
-    email_sending_account = var.sender_email != null ? "DEVELOPER" : "COGNITO_DEFAULT"
+    source_arn            = var.email_identity_arn
+    email_sending_account = var.email_identity_arn != null ? "DEVELOPER" : "COGNITO_DEFAULT"
     # Customize the name that users see in the "From" section of their inbox, so that it's clearer who the email is from.
     # This name also needs to be updated manually in the Cognito console for each environment's Advanced Security emails.
-    from_email_address     = var.sender_email != null ? (var.sender_display_name != null ? "${var.sender_display_name} <${var.sender_email}>" : var.sender_email) : null
-    reply_to_email_address = var.reply_to_email != null ? var.reply_to_email : null
+    from_email_address     = var.email_identity_arn != null ? (var.sender_display_name != null ? "${var.sender_display_name} <${var.sender_email}>" : var.sender_email) : null
+    reply_to_email_address = var.reply_to_email
   }
 
   password_policy {

infra/modules/identity-provider/resources/variables.tf

@@ -1,3 +1,9 @@
+variable "email_identity_arn" {
+  type        = string
+  description = "The arn of the SESv2 email identity to use to send emails"
+  default     = null
+}
+
 variable "is_temporary" {
   description = "Whether the service is meant to be spun up temporarily (e.g. for automated infra tests). This is used to disable deletion protection."
   type        = bool