feat(auth): Add email MFA support to Amplify Auth construct (#3036)

## Problem

This PR adds support for email-based multi-factor authentication (MFA)
to the Amplify Auth construct. Previously, the Auth construct only
supported SMS and TOTP MFA methods, limiting authentication options for
applications that prefer
email-based verification.

Issue number, if available:  
- aws-amplify/amplify-ui#6590
- #2159


## Changes
• **Auth Construct**: Added email MFA configuration support in
construct.ts with new type definitions in types.ts
• **API Updates**: Extended public API to include email MFA options with
TypeScript types
• **Client Configuration**: Updated all client config schema versions
(v1, v1.1-v1.4) to support email MFA settings
• **Documentation**: Updated API.md and README.md with email MFA usage
examples
• **Test Coverage**: Added comprehensive unit tests for email MFA
functionality

**Corresponding docs PR, if applicable:**
- aws-amplify/docs#8465
## Validation
• **Unit Tests**: Added 56 lines of test coverage in construct.test.ts
validating email MFA configuration and behavior
• **Manual testing**: I tested on a amplify sample app which is linked
locally with amplify-backend. I set the email MFA to true and false and
checked it updates correctly in the Cognito user pool

## Checklist

- [ ] If this PR includes a functional change to the runtime behavior of
the code, I have added or updated automated test coverage for this
change.
- [ ] If this PR requires a change to the [Project Architecture
README](../PROJECT_ARCHITECTURE.md), I have included that update in this
PR.
- [ ] If this PR requires a docs update, I have linked to that docs PR
above.
- [ ] If this PR modifies E2E tests, makes changes to resource
provisioning, or makes SDK calls, I have run the PR checks with the
`run-e2e` label set.

_By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license._

Author: osama-rizk

.changeset/cuddly-clowns-guess.md

@@ -0,0 +1,9 @@
+---
+'@aws-amplify/auth-construct': minor
+'@aws-amplify/client-config': minor
+'@aws-amplify/backend-auth': minor
+'@aws-amplify/backend': minor
+'@aws-amplify/seed': minor
+---
+
+feat(auth): Added support for email-MFA in Amplify Auth construct

packages/auth-construct/API.md

@@ -144,13 +144,22 @@ export type MFA = {
     mode: 'OPTIONAL' | 'REQUIRED';
 } & MFASettings);
 
+// @public
+export type MFAEmailSettings = boolean;
+
 // @public
 export type MFASettings = {
+    totp?: MFATotpSettings;
+    sms?: MFASmsSettings;
+    email: MFAEmailSettings;
+} | {
     totp?: MFATotpSettings;
     sms: MFASmsSettings;
+    email?: MFAEmailSettings;
 } | {
     totp: MFATotpSettings;
     sms?: MFASmsSettings;
+    email?: MFAEmailSettings;
 };
 
 // @public

packages/auth-construct/README.md

@@ -47,6 +47,36 @@ new AmplifyAuth(stack, 'Auth', {
 });
 ```
 
+### Email login with email MFA
+
+In this example, you will create a stack with email login and email MFA enabled. Note that email MFA requires an email sender configuration.
+
+```ts
+import { App, Stack } from 'aws-cdk-lib';
+import { AmplifyAuth } from '@aws-amplify/auth-construct';
+
+const app = new App();
+const stack = new Stack(app, 'AuthStack');
+
+new AmplifyAuth(stack, 'Auth', {
+  loginWith: {
+    email: true,
+  },
+  multifactor: {
+    mode: 'OPTIONAL',
+    email: true,
+    sms: false,
+    totp: false,
+  },
+  senders: {
+    email: {
+      fromEmail: '[email protected]',
+      fromName: 'My App',
+    },
+  },
+});
+```
+
 ### Customized email and phone login with external login providers
 
 In this example, you will create a stack with email, phone, and external login providers. Additionally, you can customize the email and phone verification messages.

packages/auth-construct/src/construct.test.ts

@@ -1169,6 +1169,62 @@ void describe('Auth construct', () => {
       assert.equal(outputs['mfaConfiguration']['Value'], 'ON');
     });
 
+    void it('enables email MFA when email is set to true', () => {
+      new AmplifyAuth(stack, 'test', {
+        loginWith: { email: true },
+        multifactor: { mode: 'OPTIONAL', email: true },
+        senders: {
+          email: {
+            fromEmail: '[email protected]',
+            fromName: 'Example.com',
+          },
+        },
+      });
+
+      const template = Template.fromStack(stack);
+      template.hasResourceProperties('AWS::Cognito::UserPool', {
+        EnabledMfas: ['EMAIL_OTP'],
+      });
+      const outputs = template.findOutputs('*');
+      assert.equal(outputs['mfaTypes']['Value'], '["EMAIL"]');
+      assert.equal(outputs['mfaConfiguration']['Value'], 'OPTIONAL');
+    });
+
+    void it('enables multiple MFA types including email', () => {
+      new AmplifyAuth(stack, 'test', {
+        loginWith: { email: true },
+        multifactor: { mode: 'REQUIRED', sms: true, totp: true, email: true },
+        senders: {
+          email: {
+            fromEmail: '[email protected]',
+            fromName: 'Example.com',
+          },
+        },
+      });
+
+      const template = Template.fromStack(stack);
+      template.hasResourceProperties('AWS::Cognito::UserPool', {
+        EnabledMfas: ['SMS_MFA', 'SOFTWARE_TOKEN_MFA', 'EMAIL_OTP'],
+      });
+      const outputs = template.findOutputs('*');
+      assert.equal(outputs['mfaTypes']['Value'], '["SMS","TOTP","EMAIL"]');
+      assert.equal(outputs['mfaConfiguration']['Value'], 'ON');
+    });
+
+    void it('does not enable email MFA when email is set to false', () => {
+      new AmplifyAuth(stack, 'test', {
+        loginWith: { email: true },
+        multifactor: { mode: 'OPTIONAL', sms: true, email: false },
+      });
+
+      const template = Template.fromStack(stack);
+      template.hasResourceProperties('AWS::Cognito::UserPool', {
+        EnabledMfas: ['SMS_MFA'],
+      });
+      const outputs = template.findOutputs('*');
+      assert.equal(outputs['mfaTypes']['Value'], '["SMS"]');
+    });
+
     void it('updates socialProviders and oauth outputs when external providers are present', () => {
       new AmplifyAuth(stack, 'test', {
         loginWith: {

packages/auth-construct/src/construct.ts

@@ -231,6 +231,7 @@ export class AmplifyAuth
     if (!(cfnUserPool instanceof CfnUserPool)) {
       throw Error('Could not find CfnUserPool resource in stack.');
     }
+
     const cfnUserPoolClient = userPoolClient.node.findChild(
       'Resource',
     ) as CfnUserPoolClient;
@@ -810,7 +811,7 @@ export class AmplifyAuth
    * Convert user friendly Mfa type to cognito Mfa type.
    * This eliminates the need for users to import cognito.Mfa.
    * @param mfa - MFA settings
-   * @returns cognito MFA type (sms or totp)
+   * @returns cognito MFA type (sms, totp, or email)
    */
   private getMFAType = (
     mfa: AuthProps['multifactor'],
@@ -819,6 +820,7 @@ export class AmplifyAuth
       ? {
           sms: mfa.sms ? true : false,
           otp: mfa.totp ? true : false,
+          email: mfa.email ? true : false,
         }
       : undefined;
   };
@@ -1222,14 +1224,18 @@ export class AmplifyAuth
     // extract the MFA types from the UserPool resource
     output.mfaTypes = Lazy.string({
       produce: () => {
+        const enabledMfas = cfnUserPool.enabledMfas ?? [];
         const mfaTypes: string[] = [];
-        (cfnUserPool.enabledMfas ?? []).forEach((type) => {
+        enabledMfas.forEach((type) => {
           if (type === 'SMS_MFA') {
             mfaTypes.push('SMS');
           }
           if (type === 'SOFTWARE_TOKEN_MFA') {
             mfaTypes.push('TOTP');
           }
+          if (type === 'EMAIL_OTP') {
+            mfaTypes.push('EMAIL');
+          }
         });
         return JSON.stringify(mfaTypes);
       },

packages/auth-construct/src/index.ts

@@ -13,6 +13,7 @@ export {
   VerificationEmailWithLink,
   MFA,
   MFASmsSettings,
+  MFAEmailSettings,
   MFATotpSettings,
   MFASettings,
   PhoneNumberLogin,

packages/auth-construct/src/types.ts

@@ -120,20 +120,30 @@ export type MFASmsSettings =
        */
       smsMessage: (createCode: () => string) => string;
     };
+/**
+ * If true, the MFA token is sent to the user via email.
+ */
+export type MFAEmailSettings = boolean;
 /**
  * If true, the MFA token is a time-based one time password that is generated by a hardware or software token
  * @see - https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-mfa-totp.html
  */
 export type MFATotpSettings = boolean;
 /**
- * Configure the MFA types that users can use. At least one of totp or sms is required.
+ * Configure the MFA types that users can use. At least one of totp, sms, or email is required.
  */
 export type MFASettings =
+  | {
+      totp?: MFATotpSettings;
+      sms?: MFASmsSettings;
+      email: MFAEmailSettings;
+    }
   | {
       totp?: MFATotpSettings;
       sms: MFASmsSettings;
+      email?: MFAEmailSettings;
     }
-  | { totp: MFATotpSettings; sms?: MFASmsSettings };
+  | { totp: MFATotpSettings; sms?: MFASmsSettings; email?: MFAEmailSettings };
 
 /**
  * MFA configuration. MFA settings are required if the mode is either "OPTIONAL" or "REQUIRED"

packages/backend-auth/src/lambda/reference_auth_initializer.ts

@@ -430,6 +430,10 @@ export class ReferenceAuthInitializer {
     if (userPoolMFA.SoftwareTokenMfaConfiguration?.Enabled) {
       mfaTypes.push('TOTP');
     }
+
+    if (userPoolMFA.EmailMfaConfiguration) {
+      mfaTypes.push('EMAIL_MFA');
+    }
     // social providers
     const socialProviders: string[] = [];
     if (userPoolProviders) {

packages/client-config/API.md

@@ -253,7 +253,7 @@ interface AWSAmplifyBackendOutputs {
         user_verification_types?: ('email' | 'phone_number')[];
         unauthenticated_identities_enabled?: boolean;
         mfa_configuration?: 'NONE' | 'OPTIONAL' | 'REQUIRED';
-        mfa_methods?: ('SMS' | 'TOTP')[];
+        mfa_methods?: ('SMS' | 'TOTP' | 'EMAIL')[];
         groups?: {
             [k: string]: AmplifyUserGroupConfig;
         }[];

packages/client-config/src/client-config-schema/client_config_v1.4.ts

@@ -185,7 +185,7 @@ export interface AWSAmplifyBackendOutputs {
     user_verification_types?: ('email' | 'phone_number')[];
     unauthenticated_identities_enabled?: boolean;
     mfa_configuration?: 'NONE' | 'OPTIONAL' | 'REQUIRED';
-    mfa_methods?: ('SMS' | 'TOTP')[];
+    mfa_methods?: ('SMS' | 'TOTP' | 'EMAIL')[];
     groups?: {
       [k: string]: AmplifyUserGroupConfig;
     }[];