chore: add explicit error for signin cancelation (#1073)

During sign-in with the Cognito hosted web UI, a Chrome Custom tab will
pop up. The user may fill in their sign-in information. However, they
may also exit out of the tab, in which case the sign-in will be
cancelled.

The current behavior is to fire an exception on the onError callback
when this occurs. That exception looks like this:
```
AuthException{
  message=Sign in with web UI failed
  cause=[...mobile client...] AuthNavigationException{
    message=user cancelled
  }
  recoverySuggestion=See attached exception for more details
}
```

This commit updates the exception that gets returned, to something more
specific, that a user could catch explicitly:
```
UserCancelledException{
  message=The user cancelled the sign-in attempt, so it did not complete.
  cause=[...mobile client...] AuthNavigationException {
    message=user cancelled
  }
  recoverySuggestion=To recover: catch this error, and show the sign-in screen again.
}
```

With this change, the caller may catch the cancellation exception in a
`when` block:
```kotlin
Amplify.Auth.signInWithWebUI(this, { /* result .. */ }, { error ->
    when (error) {
        is UserCancelledException -> Log.w("TAG", "sign-in cancelled")
        else ->  Log.e("xx", "Login failed.", error)
    }
}
```

This commit also applies similar updates to the sign-out method.

Related: aws-amplify/amplify-swift#982

Author: jamesonwilliams

aws-auth-cognito/src/main/java/com/amplifyframework/auth/cognito/AWSCognitoAuthPlugin.java

@@ -83,6 +83,7 @@
 import com.amazonaws.mobile.client.results.UserCodeDeliveryDetails;
 import com.amazonaws.mobile.config.AWSConfiguration;
 import com.amazonaws.mobileconnectors.cognitoauth.AuthClient;
+import com.amazonaws.mobileconnectors.cognitoauth.exceptions.AuthNavigationException;
 import com.amazonaws.mobileconnectors.cognitoidentityprovider.util.CognitoJWTParser;
 import com.amazonaws.services.cognitoidentity.model.NotAuthorizedException;
 import org.json.JSONException;
@@ -934,6 +935,12 @@ public void onError(Exception error) {
                             // global sign out by locally signing them out here.
                             if (error instanceof NotAuthorizedException) {
                                 signOutLocally(options, onSuccess, onError);
+                            } else if (error instanceof AuthNavigationException) {
+                                // User cancelled the sign-out screen.
+                                onError.accept(new AuthException.UserCancelledException(
+                                    "The user cancelled the sign-out attempt.", error,
+                                    "To recover, catch this error, and retry sign-out."
+                                ));
                             } else {
                                 // Any other runtime exception means global sign out failed for another reason
                                 // (e.g. device offline), in which case we pass that error back to the customer.
@@ -989,6 +996,12 @@ public void onError(Exception error) {
                                     "Failed to sign out since Auth is already signed out",
                                     "No need to sign out - you already are!"
                             ));
+                        } else if (error instanceof AuthNavigationException) {
+                            // User cancelled the sign-out screen.
+                            onError.accept(new AuthException.UserCancelledException(
+                                "The user cancelled the sign-out attempt.", error,
+                                "To recover, catch this error, and retry sign-out."
+                            ));
                         } else {
                             onError.accept(new AuthException(
                                     "Failed to sign out",
@@ -1061,13 +1074,17 @@ public void onResult(UserStateDetails details) {
 
             @Override
             public void onError(Exception error) {
-                onException.accept(
-                        new AuthException(
-                                "Sign in with web UI failed",
-                                error,
-                                "See attached exception for more details"
-                        )
-                );
+                if (error instanceof AuthNavigationException) {
+                    onException.accept(new AuthException.UserCancelledException(
+                        "The user cancelled the sign-in attempt, so it did not complete.",
+                        error, "To recover: catch this error, and show the sign-in screen again."
+                    ));
+                } else {
+                    onException.accept(new AuthException(
+                        "Sign-in with web UI failed", error,
+                        "See attached exception for more details"
+                    ));
+                }
             }
         });
     }

core/src/main/java/com/amplifyframework/auth/AuthException.java

@@ -449,6 +449,23 @@ public FailedAttemptsLimitExceededException(Throwable cause) {
         }
     }
 
+    /**
+     * Could not complete an action because it was cancelled by the user.
+     */
+    public static class UserCancelledException extends AuthException {
+        private static final long serialVersionUID = 1L;
+
+        /**
+         * Constructs an {@link UserCancelledException}.
+         * @param message Describes why the error has occurred
+         * @param cause An underlying cause of the error
+         * @param recoverySuggestion How to remedy the error, if possible
+         */
+        public UserCancelledException(String message, Throwable cause, String recoverySuggestion) {
+            super(message, cause, recoverySuggestion);
+        }
+    }
+
     /**
      * Allows the user to specify whether guest access is enabled or not since this can affect which
      * recovery message should be included.