feat: Add support for custom Lambda function email senders in Auth construct

.changeset/curvy-pans-brake.md

@@ -0,0 +1,8 @@
+---
+'@aws-amplify/auth-construct': minor
+'@aws-amplify/backend-auth': minor
+'@aws-amplify/backend': minor
+'@aws-amplify/integration-tests': minor
+---
+
+Add support for custom Lambda function email senders in Auth construct

.eslint_dictionary.json

@@ -40,6 +40,7 @@
   "datasync",
   "debounce",
   "declarator",
+  "decrypt",
   "deployer",
   "deprecations",
   "deprecator",
@@ -146,6 +147,7 @@
   "sigint",
   "signout",
   "signup",
+  "SKey",
   "sms",
   "stderr",
   "stdin",
@@ -159,6 +161,7 @@
   "synthing",
   "testname",
   "testnamebucket",
+  "testuser",
   "timestamps",
   "tmpdir",
   "todos",

packages/auth-construct/API.md

@@ -9,6 +9,7 @@ import { AuthResources } from '@aws-amplify/plugin-types';
 import { aws_cognito } from 'aws-cdk-lib';
 import { BackendOutputStorageStrategy } from '@aws-amplify/plugin-types';
 import { Construct } from 'constructs';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
 import { NumberAttributeConstraints } from 'aws-cdk-lib/aws-cognito';
 import { ResourceProvider } from '@aws-amplify/plugin-types';
 import { SecretValue } from 'aws-cdk-lib';
@@ -47,7 +48,7 @@ export type AuthProps = {
         externalProviders?: ExternalProviderOptions;
     };
     senders?: {
-        email: Pick<UserPoolSESOptions, 'fromEmail' | 'fromName' | 'replyTo'>;
+        email: Pick<UserPoolSESOptions, 'fromEmail' | 'fromName' | 'replyTo'> | CustomEmailSender;
     };
     userAttributes?: UserAttributes;
     multifactor?: MFA;
@@ -84,6 +85,12 @@ export type CustomAttributeString = CustomAttributeBase & StringAttributeConstra
     dataType: 'String';
 };
 
+// @public
+export type CustomEmailSender = {
+    handler: IFunction;
+    kmsKeyArn?: string;
+};
+
 // @public
 export type EmailLogin = true | EmailLoginSettings;
 

packages/auth-construct/src/construct.ts

@@ -34,6 +34,7 @@ import {
   UserPoolIdentityProviderOidc,
   UserPoolIdentityProviderSaml,
   UserPoolIdentityProviderSamlMetadataType,
+  UserPoolOperation,
   UserPoolProps,
 } from 'aws-cdk-lib/aws-cognito';
 import { FederatedPrincipal, Role } from 'aws-cdk-lib/aws-iam';
@@ -51,6 +52,7 @@ import {
   StackMetadataBackendOutputStorageStrategy,
 } from '@aws-amplify/backend-output-storage';
 import * as path from 'path';
+import { IKey, Key } from 'aws-cdk-lib/aws-kms';
 
 type DefaultRoles = { auth: Role; unAuth: Role };
 type IdentityProviderSetupResult = {
@@ -130,6 +132,11 @@ export class AmplifyAuth
       role: Role;
     };
   } = {};
+  /**
+   * The KMS key used for encrypting custom email sender data.
+   * This is only set when using a custom email sender.
+   */
+  private customEmailSenderKMSkey: IKey | undefined;
 
   /**
    * Create a new Auth construct with AuthProps.
@@ -141,24 +148,39 @@ export class AmplifyAuth
     props: AuthProps = DEFAULTS.IF_NO_PROPS_PROVIDED
   ) {
     super(scope, id);
-
     this.name = props.name ?? '';
     this.domainPrefix = props.loginWith.externalProviders?.domainPrefix;
-
     // UserPool
     this.computedUserPoolProps = this.getUserPoolProps(props);
+
     this.userPool = new cognito.UserPool(
       this,
       `${this.name}UserPool`,
       this.computedUserPoolProps
     );
+    /**
+     * Configure custom email sender for Cognito User Pool
+     * Grant necessary permissions for Lambda function to decrypt emails
+     * and allow Cognito to invoke the Lambda function
+     */
+    if (
+      props.senders?.email &&
+      'handler' in props.senders.email &&
+      this.customEmailSenderKMSkey
+    ) {
+      this.customEmailSenderKMSkey.grantDecrypt(props.senders.email.handler);
+      this.customEmailSenderKMSkey.grantEncrypt(props.senders.email.handler);
+      this.userPool.addTrigger(
+        UserPoolOperation.of('customEmailSender'),
+        props.senders.email.handler
+      );
+    }
 
     // UserPool - External Providers (Oauth, SAML, OIDC) and User Pool Domain
     this.providerSetupResult = this.setupExternalProviders(
       this.userPool,
       props.loginWith
     );
-
     // UserPool Client
     const userPoolClient = new cognito.UserPoolClient(
       this,
@@ -478,7 +500,30 @@ export class AmplifyAuth
       },
       { standardAttributes: {}, customAttributes: {} }
     );
-
+    /**
+     * Handle KMS key for custom email sender
+     * If a custom email sender is provided, we either use the provided KMS key ARN
+     * or create a new KMS key if one is not provided.
+     */
+    if (props.senders?.email && 'handler' in props.senders.email) {
+      if (props.senders.email.kmsKeyArn) {
+        // Use the provided KMS key ARN
+        this.customEmailSenderKMSkey = Key.fromKeyArn(
+          this,
+          `${this.name}CustomSenderKey`,
+          props.senders.email.kmsKeyArn
+        );
+      } else {
+        // Create a new KMS key if not provided
+        this.customEmailSenderKMSkey = new Key(
+          props.senders.email.handler.stack,
+          `${this.name}CustomSenderKey`,
+          {
+            enableKeyRotation: true,
+          }
+        );
+      }
+    }
     const userPoolProps: UserPoolProps = {
       signInCaseSensitive: DEFAULTS.SIGN_IN_CASE_SENSITIVE,
       signInAliases: {
@@ -503,15 +548,15 @@ export class AmplifyAuth
       customAttributes: {
         ...customAttributes,
       },
-      email: props.senders
-        ? cognito.UserPoolEmail.withSES({
-            fromEmail: props.senders.email.fromEmail,
-            fromName: props.senders.email.fromName,
-            replyTo: props.senders.email.replyTo,
-            sesRegion: Stack.of(this).region,
-          })
-        : undefined,
-
+      email:
+        props.senders && 'fromEmail' in props.senders.email
+          ? cognito.UserPoolEmail.withSES({
+              fromEmail: props.senders.email.fromEmail,
+              fromName: props.senders.email.fromName,
+              replyTo: props.senders.email.replyTo,
+              sesRegion: Stack.of(this).region,
+            })
+          : undefined,
       selfSignUpEnabled: DEFAULTS.ALLOW_SELF_SIGN_UP,
       mfa: mfaMode,
       mfaMessage: this.getMFAMessage(props.multifactor),
@@ -528,6 +573,7 @@ export class AmplifyAuth
               props.loginWith.email?.userInvitation
             )
           : undefined,
+      customSenderKmsKey: this.customEmailSenderKMSkey,
     };
     return userPoolProps;
   };

packages/auth-construct/src/index.ts

@@ -26,6 +26,7 @@ export {
   CustomAttributeBoolean,
   CustomAttributeDateTime,
   CustomAttributeBase,
+  CustomEmailSender,
 } from './types.js';
 export { AmplifyAuth } from './construct.js';
 export { triggerEvents } from './trigger_events.js';

packages/auth-construct/src/types.ts

@@ -9,6 +9,7 @@ import {
   UserPoolIdentityProviderSamlMetadata,
   UserPoolSESOptions,
 } from 'aws-cdk-lib/aws-cognito';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
 export type VerificationEmailWithLink = {
   /**
    * The type of verification. Must be one of "CODE" or "LINK".
@@ -380,6 +381,14 @@ export type CustomAttribute =
 export type UserAttributes = StandardAttributes &
   Record<`custom:${string}`, CustomAttribute>;
 
+/**
+ * CustomEmailSender type for configuring a custom Lambda function for email sending
+ */
+export type CustomEmailSender = {
+  handler: IFunction;
+  kmsKeyArn?: string;
+};
+
 /**
  * Input props for the AmplifyAuth construct
  */
@@ -417,11 +426,15 @@ export type AuthProps = {
    */
   senders?: {
     /**
-     * Configure Cognito to send emails from SES
+     * Configure Cognito to send emails from SES or a custom message trigger
      * SES configurations enable the use of customized email sender addresses and names
+     * Custom message triggers enable the use of third-party email providers when sending email notifications to users
      * @see https://docs.amplify.aws/react/build-a-backend/auth/moving-to-production/#email
+     * @see https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-email-sender.html
      */
-    email: Pick<UserPoolSESOptions, 'fromEmail' | 'fromName' | 'replyTo'>;
+    email:
+      | Pick<UserPoolSESOptions, 'fromEmail' | 'fromName' | 'replyTo'>
+      | CustomEmailSender;
   };
   /**
    * The set of attributes that are required for every user in the user pool. Read more on attributes here - https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html

packages/backend-auth/API.md

@@ -5,6 +5,7 @@
 ```ts
 
 import { AmazonProviderProps } from '@aws-amplify/auth-construct';
+import { AmplifyFunction } from '@aws-amplify/plugin-types';
 import { AppleProviderProps } from '@aws-amplify/auth-construct';
 import { AuthProps } from '@aws-amplify/auth-construct';
 import { AuthResources } from '@aws-amplify/plugin-types';
@@ -16,12 +17,14 @@ import { ExternalProviderOptions } from '@aws-amplify/auth-construct';
 import { FacebookProviderProps } from '@aws-amplify/auth-construct';
 import { FunctionResources } from '@aws-amplify/plugin-types';
 import { GoogleProviderProps } from '@aws-amplify/auth-construct';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
 import { OidcProviderProps } from '@aws-amplify/auth-construct';
 import { ResourceAccessAcceptor } from '@aws-amplify/plugin-types';
 import { ResourceAccessAcceptorFactory } from '@aws-amplify/plugin-types';
 import { ResourceProvider } from '@aws-amplify/plugin-types';
 import { StackProvider } from '@aws-amplify/plugin-types';
 import { TriggerEvent } from '@aws-amplify/auth-construct';
+import { UserPoolSESOptions } from 'aws-cdk-lib/aws-cognito';
 
 // @public
 export type ActionIam = 'addUserToGroup' | 'createGroup' | 'createUser' | 'deleteGroup' | 'deleteUser' | 'deleteUserAttributes' | 'disableUser' | 'enableUser' | 'forgetDevice' | 'getDevice' | 'getGroup' | 'getUser' | 'listUsers' | 'listUsersInGroup' | 'listGroups' | 'listDevices' | 'listGroupsForUser' | 'removeUserFromGroup' | 'resetUserPassword' | 'setUserMfaPreference' | 'setUserPassword' | 'setUserSettings' | 'updateDeviceStatus' | 'updateGroup' | 'updateUserAttributes';
@@ -36,10 +39,13 @@ export type AmazonProviderFactoryProps = Omit<AmazonProviderProps, 'clientId' |
 };
 
 // @public (undocumented)
-export type AmplifyAuthProps = Expand<Omit<AuthProps, 'outputStorageStrategy' | 'loginWith'> & {
+export type AmplifyAuthProps = Expand<Omit<AuthProps, 'outputStorageStrategy' | 'loginWith' | 'senders'> & {
     loginWith: Expand<AuthLoginWithFactoryProps>;
     triggers?: Partial<Record<TriggerEvent, ConstructFactory<ResourceProvider<FunctionResources>>>>;
     access?: AuthAccessGenerator;
+    senders?: {
+        email: Pick<UserPoolSESOptions, 'fromEmail' | 'fromName' | 'replyTo'> | CustomEmailSender;
+    };
 }>;
 
 // @public
@@ -80,6 +86,12 @@ export type AuthLoginWithFactoryProps = Omit<AuthProps['loginWith'], 'externalPr
 // @public (undocumented)
 export type BackendAuth = ResourceProvider<AuthResources> & ResourceAccessAcceptorFactory<AuthRoleName | string> & StackProvider;
 
+// @public
+export type CustomEmailSender = {
+    handler: ConstructFactory<AmplifyFunction> | IFunction;
+    kmsKeyArn?: string;
+};
+
 // @public
 export const defineAuth: (props: AmplifyAuthProps) => ConstructFactory<BackendAuth>;