diff --git a/src/fragments/lib-v1/auth/android/signin/20_confirmSignUp.mdx b/src/fragments/lib-v1/auth/android/signin/20_confirmSignUp.mdx index be6a688b9e2..5a1a8195bbe 100644 --- a/src/fragments/lib-v1/auth/android/signin/20_confirmSignUp.mdx +++ b/src/fragments/lib-v1/auth/android/signin/20_confirmSignUp.mdx @@ -57,3 +57,9 @@ RxAmplify.Auth.confirmSignUp("username", "the code you received via email") + +You will know the sign up flow is complete if you see the following in your console window: + +```console +Confirm signUp succeeded +``` diff --git a/src/fragments/lib-v1/auth/android/signin/30_signIn.mdx b/src/fragments/lib-v1/auth/android/signin/30_signIn.mdx index 7437e3856a8..4d127003641 100644 --- a/src/fragments/lib-v1/auth/android/signin/30_signIn.mdx +++ b/src/fragments/lib-v1/auth/android/signin/30_signIn.mdx @@ -55,3 +55,9 @@ RxAmplify.Auth.signIn("username", "password") + +You will know the sign in flow is complete if you see the following in your console window: + +```console +Sign in succeeded +``` diff --git a/src/fragments/lib-v1/auth/common/mfa/flows.mdx b/src/fragments/lib-v1/auth/common/mfa/flows.mdx index 3ef933a4821..238e0f8e284 100644 --- a/src/fragments/lib-v1/auth/common/mfa/flows.mdx +++ b/src/fragments/lib-v1/auth/common/mfa/flows.mdx @@ -117,6 +117,27 @@ async function handleSignUp(username, password, phone_number, email) { + +```dart +Future signUpWithPhoneVerification( + String username, + String password, +) async { + await Amplify.Auth.signUp( + username: username, + password: password, + options: SignUpOptions( + userAttributes: { + // ... if required + AuthUserAttributeKey.email: 'test@example.com', + AuthUserAttributeKey.phoneNumber: '+18885551234', + }, + ), + ); +} +``` + + By default, you have to verify a user account after they sign up using the `confirmSignUp` API, which will send a one-time password to the user's phone number or email, depending on your Amazon Cognito configuration. @@ -159,6 +180,20 @@ async function handleSignUpConfirmation(username, confirmationCode) { + +```dart +Future confirmSignUpPhoneVerification( + String username, + String otpCode, +) async { + await Amplify.Auth.confirmSignUp( + username: username, + confirmationCode: otpCode, + ); +} +``` + + ### Handling SMS MFA challenge during Sign In After a user signs in, if they have MFA enabled for their account, a challenge will be returned that you would need to call the `confirmSignIn` API where the user provides their confirmation code sent to their phone number. @@ -200,6 +235,20 @@ async function handleSignIn(username, password) { + +```dart +Future signInWithPhoneVerification( + String username, + String password, +) async { + await Amplify.Auth.signIn( + username: username, + password: password, + ); +} +``` + + If MFA is **ON** or enabled for the user, you must call `confirmSignIn` with the OTP sent to their phone. @@ -240,6 +289,16 @@ async function handleSignInConfirmation(otpCode) { + +```dart +Future confirmSignInPhoneVerification(String otpCode) async { + await Amplify.Auth.confirmSignIn( + confirmationValue: otpCode, + ); +} +``` + + After a user has been signed in, call `updateMFAPreference` to record the MFA type as enabled for the user and optionally set it as preferred so that subsequent logins default to using this MFA type. @@ -258,6 +317,18 @@ async function handleUpdateMFAPreference() { + +```dart +Future updateMfaPreferences() async { + final cognitoPlugin = Amplify.Auth.getPlugin(AmplifyAuthCognito.pluginKey); + + await cognitoPlugin.updateMfaPreference( + sms: MfaPreference.enabled, // or .preferred + ); +} +``` + + ## Multi-factor authentication with TOTP You can use Time-based One-Time Password (TOTP) for multi-factor authentication (MFA) in your web or mobile applications. The Amplify Auth category includes support for TOTP setup and verification using authenticator apps, offering an integrated solution and enhanced security for your users. These apps, such as Google Authenticator, Microsoft Authenticator, have the TOTP algorithm built-in and work by using a shared secret key and the current time to generate short-lived, six digit passwords. @@ -350,6 +421,33 @@ function handleSignInNextSteps(output) { + +```dart +Future signInUser(String username, String password) async { + try { + final result = await Amplify.Auth.signIn( + username: username, + password: password, + ); + return _handleSignInResult(result); + } on AuthException catch (e) { + safePrint('Error signing in: ${e.message}'); + } +} + +Future _handleSignInResult(SignInResult result) async { + switch (result.nextStep.signInStep) { + // ··· + case AuthSignInStep.continueSignInWithTotpSetup: + final totpSetupDetails = result.nextStep.totpSetupDetails!; + final setupUri = totpSetupDetails.getSetupUri(appName: 'MyApp'); + safePrint('Open URI to complete setup: $setupUri'); + // ··· + } +} +``` + + The TOTP code can be obtained from the user via a text field or any other means. Once the user provides the TOTP code, call `confirmSignIn` with the TOTP code as the `challengeResponse` parameter. @@ -390,9 +488,25 @@ async function handleSignInConfirmation(totpCode) { + +```dart +Future confirmTotpUser(String totpCode) async { + try { + final result = await Amplify.Auth.confirmSignIn( + confirmationValue: totpCode, + ); + return _handleSignInResult(result); + } on AuthException catch (e) { + safePrint('Error confirming TOTP code: ${e.message}'); + } +} +``` + + + + After a user has been signed in, call `updateMFAPreference` to record the MFA type as enabled for the user and optionally set it as preferred so that subsequent logins default to using this MFA type. - ```ts import { updateMFAPreference } from 'aws-amplify/auth'; @@ -440,6 +554,20 @@ async function handleTOTPSetup() { + +```dart +Future setUpTotp() async { + try { + final totpSetupDetails = await Amplify.Auth.setUpTotp(); + final setupUri = totpSetupDetails.getSetupUri(appName: 'MyApp'); + safePrint('Open URI to complete setup: $setupUri'); + } on AuthException catch (e) { + safePrint('An error occurred setting up TOTP: $e'); + } +} +``` + + Once the Authenticator app is set up, the user must generate a TOTP code and provide it to the library. Pass the code to `verifyTOTPSetup` to complete the TOTP setup process. @@ -480,10 +608,22 @@ async function handleTOTPVerification(totpCode) { -After TOTP setup is complete, call `updateMFAPreference` to record the MFA type as enabled for the user and optionally set it as preferred so that subsequent logins default to using this MFA type. + +```dart +Future verifyTotpSetup(String totpCode) async { + try { + await Amplify.Auth.verifyTotpSetup(totpCode); + } on AuthException catch (e) { + safePrint('An error occurred verifying TOTP: $e'); + } +} +``` + +After TOTP setup is complete, call `updateMFAPreference` to record the MFA type as enabled for the user and optionally set it as preferred so that subsequent logins default to using this MFA type. + ```ts import { updateMFAPreference } from 'aws-amplify/auth'; @@ -532,6 +672,18 @@ async function handleFetchMFAPreference() { + +```dart +Future getCurrentMfaPreference() async { + final cognitoPlugin = Amplify.Auth.getPlugin(AmplifyAuthCognito.pluginKey); + + final currentPreference = await cognitoPlugin.fetchMfaPreference(); + safePrint('Enabled MFA types for user: ${currentPreference.enabled}'); + safePrint('Preferred MFA type for user: ${currentPreference.preferred}'); +} +``` + + ### Update the current user's MFA preferences Invoke the following API to update the MFA preference for the current user. @@ -558,7 +710,31 @@ async function handleUpdateMFAPreference() { + +```dart +Future updateMfaPreferences() async { + final cognitoPlugin = Amplify.Auth.getPlugin(AmplifyAuthCognito.pluginKey); + + await cognitoPlugin.updateMfaPreference( + sms: MfaPreference.enabled, + totp: MfaPreference.preferred, + ); +} +``` + + + If multiple MFA methods are enabled for the user, the `signIn` API will return `CONTINUE_SIGN_IN_WITH_MFA_SELECTION` as the next step in the auth flow. During this scenario, the user should be prompted to select the MFA method they want to use to sign in and their preference should be passed to `confirmSignIn`. + + + +If multiple MFA methods are enabled for the user, the signIn API will return continueSignInWithMFASelection as the next step in the auth flow. During this scenario, the user should be prompted to select the MFA method they want to use to sign in and their preference should be passed to confirmSignIn. + +The MFA types which are currently supported by Amplify Auth are: + +- `MfaType.sms` +- `MfaType.totp` + @@ -645,3 +821,33 @@ async function handleMFASelection(mfaType) { + + +```dart +Future _handleSignInResult(SignInResult result) async { + switch (result.nextStep.signInStep) { + // ··· + case AuthSignInStep.continueSignInWithMfaSelection: + final allowedMfaTypes = result.nextStep.allowedMfaTypes!; + final selection = await _promptUserPreference(allowedMfaTypes); + return _handleMfaSelection(selection); + // ··· + } +} + +Future _promptUserPreference(Set allowedTypes) async { + // ··· +} + +Future _handleMfaSelection(MfaType selection) async { + try { + final result = await Amplify.Auth.confirmSignIn( + confirmationValue: selection.confirmationValue, + ); + return _handleSignInResult(result); + } on AuthException catch (e) { + safePrint('Error resending code: ${e.message}'); + } +} +``` + diff --git a/src/fragments/lib-v1/auth/flutter/access_credentials/10_fetchAuthSession.mdx b/src/fragments/lib-v1/auth/flutter/access_credentials/10_fetchAuthSession.mdx index 882afe49c7c..b660900491c 100644 --- a/src/fragments/lib-v1/auth/flutter/access_credentials/10_fetchAuthSession.mdx +++ b/src/fragments/lib-v1/auth/flutter/access_credentials/10_fetchAuthSession.mdx @@ -1,21 +1,3 @@ -```dart -Future fetchAuthSession() async { - try { - final result = await Amplify.Auth.fetchAuthSession(); - safePrint('User is signed in: ${result.isSignedIn}'); - } on AuthException catch (e) { - safePrint('Error retrieving auth session: ${e.message}'); - } -} -``` - -### Retrieving AWS credentials - -Sometimes it can be helpful to retrieve the instance of the underlying plugin -which has more specific typing. In the case of Cognito, calling `fetchAuthSession` -on the Cognito plugin returns AWS-specific values such as the identity ID, -AWS credentials, and Cognito User Pool tokens. - ```dart Future fetchCognitoAuthSession() async { try { diff --git a/src/fragments/lib-v1/auth/flutter/managing_credentials/10_managing_credentials.mdx b/src/fragments/lib-v1/auth/flutter/managing_credentials/10_managing_credentials.mdx index 10a019e5ebc..48045383969 100644 --- a/src/fragments/lib-v1/auth/flutter/managing_credentials/10_managing_credentials.mdx +++ b/src/fragments/lib-v1/auth/flutter/managing_credentials/10_managing_credentials.mdx @@ -1,5 +1,3 @@ -The Amplify Auth category persists authentication-related information to make it available to other Amplify categories and to your application. - Amplify Flutter securely manages credentials and user identity information. You do not need to store, refresh, or delete credentials yourself. Amplify Flutter stores auth data on the device using platform capabilities such as [Keychain Services](https://developer.apple.com/documentation/security/keychain_services/) on iOS and macOS and [EncryptedSharedPreferences](https://developer.android.com/reference/androidx/security/crypto/EncryptedSharedPreferences) on Android. diff --git a/src/fragments/lib-v1/auth/ios/signin/20_confirmSignUp.mdx b/src/fragments/lib-v1/auth/ios/signin/20_confirmSignUp.mdx index 0d27983b0bf..d06485e78f8 100644 --- a/src/fragments/lib-v1/auth/ios/signin/20_confirmSignUp.mdx +++ b/src/fragments/lib-v1/auth/ios/signin/20_confirmSignUp.mdx @@ -37,3 +37,9 @@ func confirmSignUp(for username: String, with confirmationCode: String) -> AnyCa + +You will know the sign up flow is complete if you see the following in your console window: + +```console +Confirm signUp succeeded +``` diff --git a/src/fragments/lib-v1/auth/ios/signin/30_signIn.mdx b/src/fragments/lib-v1/auth/ios/signin/30_signIn.mdx index 8a62595f166..c726a2df517 100644 --- a/src/fragments/lib-v1/auth/ios/signin/30_signIn.mdx +++ b/src/fragments/lib-v1/auth/ios/signin/30_signIn.mdx @@ -37,3 +37,9 @@ func signIn(username: String, password: String) -> AnyCancellable { + +You will know the sign in flow is complete if you see the following in your console window: + +```console +Sign in succeeded +``` diff --git a/src/fragments/lib-v1/auth/native_common/access_credentials/common.mdx b/src/fragments/lib-v1/auth/native_common/access_credentials/common.mdx index dd5f85a26df..7622a3aa205 100644 --- a/src/fragments/lib-v1/auth/native_common/access_credentials/common.mdx +++ b/src/fragments/lib-v1/auth/native_common/access_credentials/common.mdx @@ -2,7 +2,7 @@ An intentional decision with Amplify Auth was to avoid any public methods exposi With Auth, you simply sign in and it handles everything else needed to keep the credentials up to date and vend them to the other categories. -However, if you need to access them in relation to working with an API outside Amplify or want access to AWS specific identifying information (e.g. IdentityId), you can access these implementation details by casting the result of fetchAuthSession as follows: +However, if you need to access them in relation to working with an API outside Amplify or want access to AWS specific identifying information (e.g. IdentityId), you can access these implementation by following the example below: import android0 from '/src/fragments/lib-v1/auth/android/access_credentials/10_fetchAuthSession.mdx'; diff --git a/src/fragments/lib-v1/auth/native_common/signin/common.mdx b/src/fragments/lib-v1/auth/native_common/signin/common.mdx index 67ec2f0181e..fb0e17af91d 100644 --- a/src/fragments/lib-v1/auth/native_common/signin/common.mdx +++ b/src/fragments/lib-v1/auth/native_common/signin/common.mdx @@ -44,12 +44,6 @@ import flutter8 from '/src/fragments/lib-v1/auth/flutter/signin/20_confirmSignUp -You will know the sign up flow is complete if you see the following in your console window: - -```console -Confirm signUp succeeded -``` - ## Sign in a user Implement a UI to get the username and password from the user. After the user enters the username and password you can start the sign in flow by calling the following method: @@ -66,12 +60,6 @@ import flutter11 from '/src/fragments/lib-v1/auth/flutter/signin/30_signIn.mdx'; -You will know the sign in flow is complete if you see the following in your console window: - -```console -Sign in succeeded -``` - You have now successfully registered a user and authenticated with that user's username and password with Amplify. The Authentication category supports other mechanisms for authentication such as web UI based sign in, sign in using other providers etc that you can explore in the other sections. import flutter12 from '/src/fragments/lib-v1/auth/flutter/signin/60_runtime_auth_flow.mdx'; diff --git a/src/fragments/lib-v1/auth/native_common/signout/common.mdx b/src/fragments/lib-v1/auth/native_common/signout/common.mdx index 43a57127aed..10d42b1ceb1 100644 --- a/src/fragments/lib-v1/auth/native_common/signout/common.mdx +++ b/src/fragments/lib-v1/auth/native_common/signout/common.mdx @@ -12,9 +12,15 @@ import flutter2 from '/src/fragments/lib-v1/auth/flutter/signout/10_local_signou + Calling signOut without any options will just delete the local cache and keychain of the user. If you would like to sign out of all devices, invoke the signOut api with advanced options. [Amazon Cognito now supports token revocation](https://aws.amazon.com/about-aws/whats-new/2021/06/amazon-cognito-now-supports-targeted-sign-out-through-refresh-token-revocation/) and the latest Amplify version will revoke Amazon Cognito tokens if the application is online. This means that the Cognito refresh token cannot be used anymore to generate new Access and Id Tokens. + + + +Calling signOut without any options will delete the local cache of user data and revoke the Amazon Cognito tokens if the application is online. This means that the Cognito refresh token cannot be used anymore to generate new Access and Id Tokens. + Access and Id Tokens are short-lived (60 minutes by default but can be set from 5 minutes to 1 day). After revocation, these tokens cannot be used with Cognito User Pools anymore. However, they are still valid when used with other services like AppSync or API Gateway. diff --git a/src/fragments/lib/auth/flutter/signin_web_ui/10_cli_setup.mdx b/src/fragments/lib/auth/flutter/signin_web_ui/10_cli_setup.mdx index 7611f0f2d31..d82b75a9ac0 100644 --- a/src/fragments/lib/auth/flutter/signin_web_ui/10_cli_setup.mdx +++ b/src/fragments/lib/auth/flutter/signin_web_ui/10_cli_setup.mdx @@ -20,7 +20,7 @@ In terminal, navigate to your project, run `amplify add auth` (or if you've alre ? Enter your redirect signout URI: `myapp://` ? Do you want to add another redirect signout URI - `No` + `Yes` ? Enter your redirect signout URI: `http://localhost:3000/` ? Do you want to add another redirect signout URI