Skip to content

Commit c7807f4

Browse files
authored
feat(Auth): Update docs to reflect email MFA support (#8465)
* feat(Auth): Update docs to reflect email MFA support * Fix MDX syntax error * Update email MFA callout
1 parent 1589c8e commit c7807f4

File tree

3 files changed

+36
-72
lines changed
  • src/pages/[platform]
    • build-a-backend/auth
    • deploy-and-host/sandbox-environments/seed

3 files changed

+36
-72
lines changed

src/pages/[platform]/build-a-backend/auth/concepts/multi-factor-authentication/index.mdx

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,13 @@ export const auth = defineAuth({
4949
multifactor: {
5050
mode: 'OPTIONAL',
5151
totp: true,
52+
email: true,
53+
},
54+
senders: {
55+
email: {
56+
fromEmail: 'noreply@example.com',
57+
fromName: 'My App',
58+
},
5259
},
5360
// highlight-end
5461
userAttributes: {
@@ -59,11 +66,7 @@ export const auth = defineAuth({
5966
});
6067
```
6168

62-
<Callout info>
63-
**Note:** Email-based MFA is currently not supported with `defineAuth`. We are working towards supporting this feature. For more information, visit the [feature request in GitHub](https://github.com/aws-amplify/amplify-backend/issues/2159).
6469

65-
To take advantage of this feature with an Amplify generated backend, the underlying CDK construct can be extended manually. See [overriding Cognito User Pool multi-factor authentication options](/[platform]/build-a-backend/auth/modify-resources-with-cdk/#override-cognito-userpool-multi-factor-authentication-options) for more information.
66-
</Callout>
6770

6871
When MFA is `REQUIRED` with SMS in your backend auth resource, you will need to pass the phone number during sign-up API call. If you are using the `email` or `username` as the primary sign-in mechanism, you will need to pass the `phone_number` attribute as a user attribute.
6972

@@ -856,12 +859,36 @@ If a user loses access to their TOTP device, they will need to contact an admini
856859
In a scenario where MFA is marked as "Required" in the Cognito User Pool and another MFA method is not set up, the administrator would need to first initiate an [`AdminUpdateUserAttributes`](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html) call and update the user's phone number attribute. Once this is complete, the administrator can continue changing the MFA preference to SMS as suggested above.
857860

858861
## Multi-factor authentication with EMAIL
859-
<InlineFilter filters={["react"]}>
860-
<Callout info>
861-
**Note:** Email-based MFA is currently not supported in the [Authenticator component](https://ui.docs.amplify.aws/react/connected-components/authenticator). We are working towards supporting this feature. For more information, visit the [feature request in GitHub](https://github.com/aws-amplify/amplify-ui/issues/5983).
862+
To enable email MFA, set `email: true` in your multifactor configuration and configure an email sender.
862863

864+
<Callout warning>
865+
To permit users to sign in with email MFA, your user pool must have the following configuration options:
866+
867+
- You have the Plus or Essentials feature plan in your user pool.
868+
- Your user pool sends email messages with your own Amazon SES resources.
869+
870+
For more details, see [Amazon Cognito email MFA configuration](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-mfa-sms-email-message.html).
863871
</Callout>
864-
</InlineFilter>
872+
873+
```ts title="amplify/auth/resource.ts"
874+
import { defineAuth } from '@aws-amplify/backend';
875+
876+
export const auth = defineAuth({
877+
loginWith: {
878+
email: true
879+
},
880+
multifactor: {
881+
mode: 'OPTIONAL',
882+
email: true,
883+
},
884+
senders: {
885+
email: {
886+
fromEmail: 'noreply@example.com',
887+
fromName: 'My App',
888+
},
889+
},
890+
});
891+
```
865892

866893
<InlineFilter filters={["swift"]}>
867894
<Callout info>

src/pages/[platform]/build-a-backend/auth/modify-resources-with-cdk/index.mdx

Lines changed: 1 addition & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -57,69 +57,13 @@ cfnUserPool.policies = {
5757
};
5858
```
5959

60-
## Override Cognito UserPool multi-factor authentication options
61-
62-
While Email MFA is not yet supported with `defineAuth`, this feature can be enabled by modifying the underlying CDK construct.
63-
64-
Start by ensuring your `defineAuth` resource configuration includes a compatible account recovery option and a custom SES sender.
65-
66-
```ts title="amplify/auth/resource.ts"
67-
import { defineAuth } from "@aws-amplify/backend"
68-
69-
/**
70-
* Define and configure your auth resource
71-
* @see https://docs.amplify.aws/gen2/build-a-backend/auth
72-
*/
73-
export const auth = defineAuth({
74-
loginWith: {
75-
email: true,
76-
phone: true,
77-
},
78-
multifactor: {
79-
mode: "OPTIONAL",
80-
sms: true,
81-
totp: false,
82-
},
83-
// Important! The logic to resolve this value cannot determine whether email mfa is enabled when overriding the resource.
84-
// Be sure to pick a recovery option appropriate for your application.
85-
accountRecovery: "EMAIL_AND_PHONE_WITHOUT_MFA",
86-
senders: {
87-
email: {
88-
fromEmail: "registrations@example.com",
89-
},
90-
},
91-
})
92-
```
93-
94-
Next, extend the underlying CDK construct by activating [Amazon Cognito's Advanced Security Features (ASF)](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-advanced-security.html) and add `EMAIL_OTP` to the enabled MFA options.
95-
96-
```ts title="amplify/backend.ts"
97-
import { defineBackend } from "@aws-amplify/backend"
98-
import { auth } from "./auth/resource"
99-
100-
const backend = defineBackend({
101-
auth,
102-
})
103-
104-
const { cfnUserPool } = backend.auth.resources.cfnResources
105-
106-
// enable ASF
107-
cfnUserPool.userPoolAddOns = {
108-
advancedSecurityMode: "AUDIT",
109-
}
110-
111-
// add email mfa
112-
// https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cognito-userpool.html#cfn-cognito-userpool-enabledmfas
113-
cfnUserPool.enabledMfas = [...(cfnUserPool.enabledMfas || []), "EMAIL_OTP"]
114-
```
115-
11660
{/* token validity */}
11761
{/* BYO custom idp construct */}
11862
{/* extend auth/unauth roles */}
11963

12064
<InlineFilter filters={["android","angular", "javascript", "nextjs", "react", "react-native", "swift", "vue"]}>
12165

122-
### Override Cognito UserPool to enable passwordless sign-in methods
66+
## Override Cognito UserPool to enable passwordless sign-in methods
12367

12468
You can modify the underlying Cognito user pool resource to enable sign in with passwordless methods. [Learn more about passwordless sign-in methods](/[platform]/build-a-backend/auth/concepts/passwordless/).
12569

src/pages/[platform]/deploy-and-host/sandbox-environments/seed/index.mdx

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -305,13 +305,6 @@ npx ampx sandbox seed
305305
```
306306

307307
SMS MFA follows the same pattern as Email MFA, using command line prompts for verification. Just replace `mfaPreference: "EMAIL"` with `mfaPreference: "SMS"` in your configuration. The command line experience will be identical, prompting for the SMS code instead of the email code.
308-
309-
<Callout info>
310-
**Note:** Email-based MFA is currently not supported with `defineAuth`. We are working towards supporting this feature. For more information, visit the [feature request in GitHub](https://github.com/aws-amplify/amplify-backend/issues/2159).
311-
312-
To take advantage of this feature with an Amplify generated backend, the underlying CDK construct can be extended manually. See [overriding Cognito User Pool multi-factor authentication options](/[platform]/build-a-backend/auth/modify-resources-with-cdk/#override-cognito-userpool-multi-factor-authentication-options) for more information.
313-
</Callout>
314-
315308
### Data
316309

317310
For example, if you like to seed your Data API, lets start by creating a GraphQL API with a `Todo` model with authorization mode set to `userPool`:

0 commit comments

Comments
 (0)