Merge branch 'main' into add-passwordless-android

Author: vincetran

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

@@ -209,7 +209,7 @@ RxAmplify.Auth.signIn("username", "password")
 func signIn(username: String, password: String) async {
     do {
         let signInResult = try await Amplify.Auth.signIn(
-            username: username, 
+            username: username,
             password: password
         )
         if signInResult.isSignedIn {
@@ -230,7 +230,7 @@ func signIn(username: String, password: String) async {
 func signIn(username: String, password: String) -> AnyCancellable {
     Amplify.Publisher.create {
         try await Amplify.Auth.signIn(
-            username: username, 
+            username: username,
             password: password
         )
     }.sink {
@@ -739,7 +739,7 @@ Amplify.Auth.confirmSignIn("code received via SMS",
 ```kotlin
 try {
     val result = Amplify.Auth.confirmSignIn("code received via SMS")
-    Log.i("AuthQuickstart", "Confirmed signin: $result") 
+    Log.i("AuthQuickstart", "Confirmed signin: $result")
 } catch (error: AuthException) {
     Log.e("AuthQuickstart", "Failed to confirm signin", error)
 }
@@ -1047,7 +1047,7 @@ To sign in using an external identity provider such as Google, use the `signInWi
 
 ### Update Info.plist
 
-Sign-in with web UI requires the Amplify plugin to show up the sign-in UI inside a webview. After the sign-in process is complete it will redirect back to your app. 
+Sign-in with web UI requires the Amplify plugin to show up the sign-in UI inside a webview. After the sign-in process is complete it will redirect back to your app.
 You have to enable this in your app's `Info.plist`. Right click Info.plist and then choose Open As > Source Code. Add the following entry in the URL scheme:
 
 ```xml
@@ -1135,17 +1135,28 @@ Your application's users can also sign in using passwordless methods. To learn m
 
 <InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
 
-To request an OTP code via SMS for authentication, the challenge is passed as the challenge response to the confirm sign in API.
+Pass `SMS_OTP` as the `preferredChallenge` when calling the `signIn` API in order to initiate a passwordless authentication flow with SMS OTP.
 
-Amplify will respond appropriately to Cognito and return the challenge as sign in next step: `CONFIRM_SIGN_IN_WITH_SMS_CODE`:
 
 ```ts
-const { nextStep } = await confirmSignIn({
-    challengeResponse: "SMS_OTP"
+const { nextStep: signInNextStep } = await signIn({
+	username: '+15551234567',
+	options: {
+		authFlowType: 'USER_AUTH',
+		preferredChallenge: 'SMS_OTP',
+	},
 });
 
-// nextStep.signInStep === 'CONFIRM_SIGN_IN_WITH_SMS_CODE'
-handleNextSignInStep(nextStep);
+if (signInNextStep.signInStep === 'CONFIRM_SIGN_IN_WITH_SMS_CODE') {
+	// prompt user for otp code delivered via SMS
+	const { nextStep: confirmSignInNextStep } = await confirmSignIn({
+		challengeResponse: '123456',
+	});
+
+	if (confirmSignInNextStep.signInStep === 'DONE') {
+		console.log('Sign in successful!');
+	}
+}
 ```
 
 </InlineFilter>
@@ -1339,17 +1350,27 @@ func confirmSignIn() -> AnyCancellable {
 
 <InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
 
-To request an OTP code via email for authentication, the challenge is passed as the challenge response to the confirm sign in API.
-
-Amplify will respond appropriately to Cognito and return the challenge as sign in next step: `CONFIRM_SIGN_IN_WITH_EMAIL_CODE`:
+Pass `EMAIL_OTP` as the `preferredChallenge` when calling the `signIn` API in order to initiate a passwordless authentication flow using email OTP.
 
 ```ts
-const { nextStep } = await confirmSignIn({
-    challengeResponse: "EMAIL_OTP"
+const { nextStep: signInNextStep } = await signIn({
+	username: '[email protected]',
+	options: {
+		authFlowType: 'USER_AUTH',
+		preferredChallenge: 'EMAIL_OTP',
+	},
 });
 
-// nextStep.signInStep === 'CONFIRM_SIGN_IN_WITH_EMAIL_CODE'
-handleNextSignInStep(nextStep);
+if (signInNextStep.signInStep === 'CONFIRM_SIGN_IN_WITH_EMAIL_CODE') {
+	// prompt user for otp code delivered via email
+	const { nextStep: confirmSignInNextStep } = await confirmSignIn({
+		challengeResponse: '123456',
+	});
+
+	if (confirmSignInNextStep.signInStep === 'DONE') {
+		console.log('Sign in successful!');
+	}
+}
 ```
 
 </InlineFilter>
@@ -1537,22 +1558,27 @@ func confirmSignIn() -> AnyCancellable {
 </BlockSwitcher>
 
 </InlineFilter>
-  
+
 ### WebAuthn Passkeys
 
 {/* blurb with supplemental information about handling sign-in, events, etc. */}
 
 <InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
 
-The WebAuthn credential flow is initiated by passing the challenge name to the confirm sign in api.
+Pass `WEB_AUTHN` as the `preferredChallenge` in order to initiate the passwordless authentication flow using a WebAuthn credential.
 
 ```ts
-const { nextStep } = await confirmSignIn({
-    challengeResponse: "WEB_AUTHN",
+const { nextStep: signInNextStep } = await signIn({
+	username: '[email protected]',
+	options: {
+		authFlowType: 'USER_AUTH',
+		preferredChallenge: 'WEB_AUTHN',
+	},
 });
 
-// nextStep.signInStep === 'DONE'
-handleNextSignInStep(nextStep);
+if (signInNextStep.signInStep === 'DONE') {
+	console.log('Sign in successful!');
+}
 ```
 
 </InlineFilter>
@@ -1664,28 +1690,55 @@ Using WebAuthn sign in may result in a number of possible exception types.
 
 <InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue", "android"]}>
 
-### Password or SRP
+### Password
 
-Traditional password based authentication is available from the `USER_AUTH` flow as well. To initiate this flow from select challenge, either `PASSWORD` or `PASSWORD_SRP` is passed as the challenge response.
+Pass either `PASSWORD` or `PASSWORD_SRP` as the `preferredChallenge` in order to initiate a traditional password based authentication flow.
 
 </InlineFilter>
 
 <InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
 ```ts
-const { nextStep } = await confirmSignIn({
-    challengeResponse: "PASSWORD_SRP", // or "PASSWORD"
+const { nextStep: signInNextStep } = await signIn({
+	username: '[email protected]',
+	password: 'example-password',
+	options: {
+		authFlowType: 'USER_AUTH',
+		preferredChallenge: 'PASSWORD_SRP', // or 'PASSWORD'
+	},
 });
 
-// in both cases
-// nextStep.signInStep === 'CONFIRM_SIGN_IN_WITH_PASSWORD'
-handleNextSignInStep(nextStep);
+if (confirmSignInNextStep.signInStep === 'DONE') {
+	console.log('Sign in successful!');
+}
+```
 
-const { nextStep: nextNextStep } = await confirmSignIn({
-    challengeResponse: "Test123#",
+
+### First Factor Selection
+
+Omit the `preferredChallenge` parameter to discover what first factors are available for a given user.
+
+The `confirmSignIn` API can then be used to select a challenge and initiate the associated authentication flow.
+
+```ts
+const { nextStep: signInNextStep } = await signIn({
+	username: '+15551234567',
+	options: {
+		authFlowType: 'USER_AUTH',
+	},
 });
 
-// nextNextStep.signInStep === 'DONE'
-handleNextSignInStep(nextNextStep);
+if (
+	signInNextStep.signInStep === 'CONTINUE_SIGN_IN_WITH_FIRST_FACTOR_SELECTION'
+) {
+	// present user with list of available challenges
+	console.log(`Available Challenges: ${signInNextStep.availableChallenges}`);
+
+	// respond with user selection using `confirmSignIn` API
+	const { nextStep: nextConfirmSignInStep } = await confirmSignIn({
+		challengeResponse: 'SMS_OTP', // or 'EMAIL_OTP', 'WEB_AUTHN', 'PASSWORD', 'PASSWORD_SRP'
+	});
+}
+
 ```
 </InlineFilter>