chore: add new steps and new flow type

Author: harsh62

src/pages/[platform]/build-a-backend/auth/connect-your-frontend/multi-step-sign-in/index.mdx

@@ -2030,6 +2030,19 @@ func signIn(username: String, password: String) async {
 
             // Prompt the user to enter the Email MFA code they received
             // Then invoke `confirmSignIn` api with the code
+
+        case .continueSignInWithFirstFactorSelection(let allowedFactors):
+            print("Received next step as continue sign in by selecting first factor")
+            print("Allowed factors \(allowedFactors)")
+
+            // Prompt the user to select the first factor they want to use
+            // Then invoke `confirmSignIn` api with the factor
+
+        case .confirmSignInWithPassword:
+            print("Received next step as confirm sign in with password")
+
+            // Prompt the user to enter the password
+            // Then invoke `confirmSignIn` api with the password
         
         case .continueSignInWithTOTPSetup(let setUpDetails):
             print("Received next step as continue sign in by setting up TOTP")

src/pages/[platform]/build-a-backend/auth/connect-your-frontend/sign-in/index.mdx

@@ -295,6 +295,8 @@ The `signIn` API response will include a `nextStep` property, which can be used
 | `confirmSignInWithTOTPCode` | The sign-in must be confirmed with a TOTP code from the user. Complete the process with `confirmSignIn`. |
 | `confirmSignInWithSMSMFACode` | The sign-in must be confirmed with a SMS code from the user. Complete the process with `confirmSignIn`. |
 | `confirmSignInWithOTP` | The sign-in must be confirmed with a code from the user (sent via SMS or Email). Complete the process with `confirmSignIn`. |
+| `confirmSignInWithPassword` | The user must set a new password. Complete the process with `confirmSignIn`. |
+| `continueSignInWithFirstFactorSelection` | The user must select their preferred mode of First Factor authentication. Complete the process with `confirmSignIn`. |
 | `continueSignInWithMFASelection` | The user must select their mode of MFA verification before signing in. Complete the process with `confirmSignIn`. |
 | `continueSignInWithMFASetupSelection` | The user must select their mode of MFA verification to setup. Complete the process by passing either `MFAType.email.challengeResponse` or `MFAType.totp.challengeResponse ` to `confirmSignIn`. |
 | `continueSignInWithTOTPSetup` | The TOTP setup process must be continued. Complete the process with `confirmSignIn`. |
@@ -615,6 +617,8 @@ Following sign in, you will receive a `nextStep` in the sign-in result of one of
 | `confirmSignInWithTOTPCode` | The sign-in must be confirmed with a TOTP code from the user. Complete the process with `confirmSignIn`. |
 | `confirmSignInWithSMSMFACode` | The sign-in must be confirmed with a SMS code from the user. Complete the process with `confirmSignIn`. |
 | `confirmSignInWithOTP` | The sign-in must be confirmed with a code from the user (sent via SMS or Email). Complete the process with `confirmSignIn`. |
+| `confirmSignInWithPassword` | The user must set a new password. Complete the process with `confirmSignIn`. |
+| `continueSignInWithFirstFactorSelection` | The user must select their preferred mode of First Factor authentication. Complete the process with `confirmSignIn`. |
 | `continueSignInWithMFASelection` | The user must select their mode of MFA verification before signing in. Complete the process with `confirmSignIn`. |
 | `continueSignInWithMFASetupSelection` | The user must select their mode of MFA verification to setup. Complete the process by passing either `MFAType.email.challengeResponse` or `MFAType.totp.challengeResponse ` to `confirmSignIn`. |
 | `continueSignInWithTOTPSetup` | The TOTP setup process must be continued. Complete the process with `confirmSignIn`. |

src/pages/[platform]/build-a-backend/auth/connect-your-frontend/switching-authentication-flows/index.mdx

@@ -40,6 +40,8 @@ For client side authentication there are four different flows that can be config
 
 4. `customWithoutSRP`: The `customWithoutSRP` flow is used to start authentication flow **WITHOUT** SRP and then use a series of challenge and response cycles that can be customized to meet different requirements.
 
+5. `userAuth`: The `userAuth` flow is a choice-based authentication flow that allows the user to choose from the list of available authentication methods. This flow is useful when you want to provide the user with the option to choose the authentication method. The choices that may be available to the user are `emailOTP`, `smsOTP`, `webAuthn`, `password` or `passwordSRP`.
+
 `Auth` can be configured to use the different flows at runtime by calling `signIn` with `AuthSignInOptions`'s `authFlowType` as `AuthFlowType.userPassword`, `AuthFlowType.customAuthWithoutSrp` or `AuthFlowType.customAuthWithSrp`. If you do not specify the `AuthFlowType` in `AuthSignInOptions`, the default flow (`AuthFlowType.userSRP`) will be used.
 
 <Callout>
@@ -50,6 +52,31 @@ Runtime configuration will take precedence and will override any auth flow type
 
 > For more information about authentication flows, please visit [Amazon Cognito developer documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-authentication-flow.html#amazon-cognito-user-pools-custom-authentication-flow)
 
+## USER_AUTH (Choice-based authentication) flow
+
+A use case for the `USER_AUTH` authentication flow is to provide the user with the option to choose the authentication method. The choices that may be available to the user are `emailOTP`, `smsOTP`, `webAuthn`, `password` or `passwordSRP`.
+
+```swift
+let pluginOptions = AWSAuthSignInOptions(
+    authFlowType: .userAuth)
+let signInResult = try await Amplify.Auth.signIn(
+    username: username,
+    password: password,
+    options: .init(pluginOptions: pluginOptions))
+guard case .continueSignInWithFirstFactorSelection(let availableFactors) = signInResult.nextStep else {
+    return
+}
+print("Available factors: \(availableFactors)")
+```
+
+The selection of the authentication method is done by the user. The user can choose from the available factors and proceed with the selected factor. You should call the `confirmSignIn` API with the selected factor to continue the sign-in process. Followign is an example if you want to proceed with the `emailOTP` factor selection:
+
+```swift
+// Select emailOTP as the factor
+var confirmSignInResult = try await Amplify.Auth.confirmSignIn(
+    challengeResponse: AuthFactorType.emailOTP.challengeResponse)
+```
+
 ## USER_PASSWORD_AUTH flow
 
 A use case for the `USER_PASSWORD_AUTH` authentication flow is migrating users into Amazon Cognito
@@ -92,6 +119,7 @@ const backend = defineBackend({
 backend.auth.resources.cfnResources.cfnUserPoolClient.explicitAuthFlows = [
   "ALLOW_USER_PASSWORD_AUTH",
   "ALLOW_USER_SRP_AUTH",
+  "ALLOW_USER_AUTH",
   "ALLOW_REFRESH_TOKEN_AUTH"
 ];
 // highlight-end