feat(auth): update passwordless authentication configuration guide (#8478)

Author: ahmedhamouda78

src/pages/[platform]/build-a-backend/auth/concepts/passwordless/index.mdx

@@ -34,15 +34,40 @@ Amplify supports the use of passwordless authentication flows using the followin
 - [WebAuthn passkey](#webauthn-passkey)
 
 Passwordless authentication removes the security risks and user friction associated with traditional passwords.
-{/* add more color */}
 
-<Callout warning>
+## Configure passwordless authentication
 
-**Warning:** Passwordless configuration is currently not available in `defineAuth`. We are currently working towards enabling support for passwordless configurations. [Visit the GitHub issue to track the progress](https://github.com/aws-amplify/amplify-backend/issues/2276)
+You can enable passwordless authentication methods directly in your `defineAuth` configuration. Passwordless methods are used alongside traditional password-based authentication, giving users multiple options to sign in.
 
-</Callout>
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from '@aws-amplify/backend';
 
-Learn how to enable passwordless sign-in flows by [overriding the Cognito UserPool to enable the sign-in methods below](/[platform]/build-a-backend/auth/modify-resources-with-cdk/#override-cognito-userpool-to-enable-passwordless-sign-in-methods).
+export const auth = defineAuth({
+  loginWith: {
+    email: {
+      otpLogin: true // Enable email OTP
+    }
+  }
+});
+```
+
+You can enable multiple passwordless methods simultaneously:
+
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from '@aws-amplify/backend';
+
+export const auth = defineAuth({
+  loginWith: {
+    email: {
+      otpLogin: true // Enable email OTP
+    },
+    phone: {
+      otpLogin: true // Enable SMS OTP
+    },
+    webAuthn: true // Enable WebAuthn passkeys
+  }
+});
+```
 
 {/* need a section about what a "preferred" factor is */}
 
@@ -54,23 +79,21 @@ SMS-based authentication uses phone numbers as the identifier and text messages
 2. They receive a text message with a time-limited code
 3. After the user enters their code they are authenticated
 
-{/* quick blurb of basic usage */}
-<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
+### Configure SMS OTP
 
-{/*  */}
-
-</InlineFilter>
-<InlineFilter filters={["android"]}>
-
-{/*  */}
-
-</InlineFilter>
-
-<InlineFilter filters={["swift"]}>
+Enable SMS OTP by setting `otpLogin: true` in your phone login configuration:
 
-{/*  */}
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from '@aws-amplify/backend';
 
-</InlineFilter>
+export const auth = defineAuth({
+  loginWith: {
+    phone: {
+      otpLogin: true
+    }
+  }
+});
+```
 
 <Callout info>
 
@@ -90,22 +113,21 @@ Email-based authentication uses email addresses for identification and verificat
 2. They receive an email message with a time-limited code
 3. After the users enters their code they are authenticated
 
-{/* quick blurb of basic usage */}
-<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
+### Configure Email OTP
 
-{/*  */}
-
-</InlineFilter>
-<InlineFilter filters={["android"]}>
+Enable Email OTP by setting `otpLogin: true` in your email login configuration:
 
-{/*  */}
-
-</InlineFilter>
-<InlineFilter filters={["swift"]}>
-
-{/*  */}
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from '@aws-amplify/backend';
 
-</InlineFilter>
+export const auth = defineAuth({
+  loginWith: {
+    email: {
+      otpLogin: true
+    }
+  }
+});
+```
 
 <Callout info>
 
@@ -123,12 +145,41 @@ WebAuthn uses biometrics or security keys for authentication, leveraging device-
 2. Their device prompts for biometric/security key verification
 3. For future logins, they'll authenticate using the same method
 
-{/* quick blurb of basic usage */}
-<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
+### Configure WebAuthn
 
-{/*  */}
+Enable WebAuthn passkeys in your auth configuration. The simplest configuration uses automatic relying party ID resolution:
+
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from '@aws-amplify/backend';
+
+export const auth = defineAuth({
+  loginWith: {
+    email: true, // Users need a sign-up method
+    webAuthn: true // Automatically resolves relying party ID
+  }
+});
+```
+
+When `webAuthn: true` is used, the relying party ID is automatically resolved:
+- In **sandbox** environments: resolves to `localhost`
+- In **branch** deployments: resolves to your Amplify app domain (e.g., `[branch].[appId].amplifyapp.com`)
+
+For production environments or custom domains, specify the relying party ID explicitly:
+
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from '@aws-amplify/backend';
+
+export const auth = defineAuth({
+  loginWith: {
+    email: true,
+    webAuthn: {
+      relyingPartyId: 'example.com',
+      userVerification: 'required' // or 'preferred' (default)
+    }
+  }
+});
+```
 
-</InlineFilter>
 <InlineFilter filters={["android"]}>
 
 You can read more about how passkeys work in the [Android developer docs](https://developer.android.com/design/ui/mobile/guides/patterns/passkeys).
@@ -140,7 +191,7 @@ Registering a passkey is supported on Android 9 (API level 28) and above.
 Using passkeys with Amplify requires following these steps:
 
 1. Deploy a Digital Asset Links file to your website granting the `get_login_creds` permission to your application. See the [Credential Manager documentation](https://developer.android.com/identity/sign-in/credential-manager#add-support-dal) for more details about this file.
-1. [Configure your Amazon Cognito user pool](/[platform]/build-a-backend/auth/modify-resources-with-cdk/#override-cognito-userpool-to-enable-passwordless-sign-in-methods) with `WEB_AUTHN` as an allowed first factor, and specify your website domain as the `WebAuthnRelyingPartyID`.
+1. Configure WebAuthn in your `defineAuth` as shown above, specifying your website domain as the `relyingPartyId`.
 1. Use the Amplify Android APIs to first [register a passkey](/[platform]/build-a-backend/auth/manage-users/manage-webauthn-credentials/#associate-webauthn-credentials) and then to [sign in with WebAuthn](/[platform]/build-a-backend/auth/connect-your-frontend/sign-in/#webauthn-passkeys).
 
 </InlineFilter>
@@ -157,3 +208,63 @@ Using passkeys with Amplify requires following these steps:
 Passwordless authentication with WebAuthn requires associating one or more credentials with the user's Amazon Cognito account. Amplify provides APIs that integrate with each platform's local authenticator to easily create, view, and delete these credential associations.
 
 [Learn more about managing WebAuthn credentials](/[platform]/build-a-backend/auth/manage-users/manage-webauthn-credentials).
+
+## Passwordless authentication
+
+When you enable passwordless authentication methods, traditional password authentication remains available. This gives users flexibility to choose their preferred authentication method:
+
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from '@aws-amplify/backend';
+
+export const auth = defineAuth({
+  loginWith: {
+    email: {
+      otpLogin: true // Email OTP enabled alongside password auth
+    }
+  }
+});
+```
+
+In this configuration, users can authenticate using either:
+- Email and password (traditional)
+- Email OTP (passwordless)
+
+You can enable multiple passwordless methods to give users even more options:
+
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from '@aws-amplify/backend';
+
+export const auth = defineAuth({
+  loginWith: {
+    email: {
+      otpLogin: true
+    },
+    phone: {
+      otpLogin: true
+    },
+    webAuthn: {
+      relyingPartyId: 'example.com'
+    }
+  }
+});
+```
+
+In this configuration, users can authenticate using:
+- Email and password
+- Email OTP
+- Phone and password
+- SMS OTP
+- WebAuthn passkeys
+
+<Callout info>
+
+When using WebAuthn, users still need a way to initially sign up (email or phone). WebAuthn credentials are then associated with their account for future sign-ins.
+
+</Callout>
+
+## Next steps
+
+- [Learn how to implement passwordless sign-in in your application](/[platform]/build-a-backend/auth/connect-your-frontend/sign-in/)
+- [Configure email settings for Email OTP](/[platform]/build-a-backend/auth/moving-to-production/#email)
+- [Configure SMS settings for SMS OTP](/[platform]/build-a-backend/auth/moving-to-production/#sms)
+- [Manage WebAuthn credentials](/[platform]/build-a-backend/auth/manage-users/manage-webauthn-credentials/)

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

@@ -65,7 +65,13 @@ cfnUserPool.policies = {
 
 ## Override Cognito UserPool to enable passwordless sign-in methods
 
-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/). 
+<Callout info>
+
+**Recommended approach:** Passwordless authentication can now be configured directly in `defineAuth` without requiring CDK overrides. [Learn how to configure passwordless authentication](/[platform]/build-a-backend/auth/concepts/passwordless/).
+
+</Callout>
+
+For advanced use cases, you can still modify the underlying Cognito user pool resource to enable sign in with passwordless methods using CDK overrides. [Learn more about passwordless sign-in methods](/[platform]/build-a-backend/auth/concepts/passwordless/). 
 
 You can also read more about how passwordless authentication flows are implemented in the [Cognito documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-authentication-flow-methods.html).
 

src/pages/[platform]/build-a-backend/auth/set-up-auth/index.mdx

@@ -47,14 +47,42 @@ export const auth = defineAuth({
 })
 ```
 
-By default, your auth resource is scaffolded using `email` as the default login mechanism. You can also configure your auth resource to allow signing in with phone numbers or an external provider such as Google, Facebook, Amazon, or Sign in with Apple.
+By default, your auth resource is scaffolded using `email` as the default login mechanism. You can also configure your auth resource to allow signing in with:
+
+- Phone numbers
+- External providers (Google, Facebook, Amazon, or Sign in with Apple)
+<InlineFilter filters={['android', 'angular', 'javascript', 'nextjs', 'react', 'react-native', 'swift', 'vue']}>
+- [Passwordless authentication](/[platform]/build-a-backend/auth/concepts/passwordless/) (Email OTP, SMS OTP, or WebAuthn passkeys)
+</InlineFilter>
 
 <Callout info>
 
 **Note:** At a minimum you will need to pass a `loginWith` value to set up how your users sign in to your app. Signing in with email and password is configured by default if you do not provide any value.
 
 </Callout>
 
+<InlineFilter filters={['android', 'angular', 'javascript', 'nextjs', 'react', 'react-native', 'swift', 'vue']}>
+
+## Enable passwordless authentication
+
+You can enable passwordless authentication methods to provide a more secure and user-friendly experience:
+
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from '@aws-amplify/backend';
+
+export const auth = defineAuth({
+  loginWith: {
+    email: {
+      otpLogin: true // Enable email-based one-time passwords
+    }
+  }
+});
+```
+
+[Learn more about passwordless authentication options](/[platform]/build-a-backend/auth/concepts/passwordless/).
+
+</InlineFilter>
+
 ## Deploy auth resource
 
 After you have chosen and defined your authentication resource, run the following command to create your resource in your personal cloud sandbox.