Logo for jsDocs.io

@aws-amplify/auth

  • Version 6.0.28
  • Published
  • 2.34 MB
  • 1 dependency
  • Apache-2.0 license

Install

npm i @aws-amplify/auth
yarn add @aws-amplify/auth
pnpm add @aws-amplify/auth

Overview

Auth category of aws-amplify

Index

Variables

Functions

Classes

Interfaces

Type Aliases

Variables

variable autoSignIn

let autoSignIn: AutoSignInCallback;

  • Signs a user in automatically after finishing the sign-up process.

    This API will automatically sign a user in if the autoSignIn flow has been completed in the following cases: - User confirmed their account with a verification code sent to their phone or email (default option). - User confirmed their account with a verification link sent to their phone or email. In order to enable this option you need to go to the Amazon Cognito [console](https://aws.amazon.com/pm/cognito), look for your userpool, then go to the Messaging tab and enable link mode inside the Verification message option. Finally you need to define the signUpVerificationMethod in your Auth config.

    Returns

    The signInOutput.

    Throws

    AutoSignInException - Thrown when the autoSignIn flow has not started, or has been cancelled/completed.

    Example 1

     Amplify.configure({
       Auth: {
        Cognito: {
       ...cognitoConfig,
       signUpVerificationMethod: "link" // the default value is "code"
      }
    	}});

    Example 2

     // handleSignUp.ts
    async function handleSignUp(
      username:string,
      password:string
    ){
      try {
        const { nextStep } = await signUp({
          username,
          password,
          options: {
            userAttributes:{ email:'email@email.com'},
            autoSignIn: true // This enables the auto sign-in flow.
          },
        });
    

        handleSignUpStep(nextStep);
    

      } catch (error) {
        console.log(error);
      }
    }
    

    // handleConfirmSignUp.ts
    async function handleConfirmSignUp(username:string, confirmationCode:string) {
      try {
        const { nextStep } = await confirmSignUp({
          username,
          confirmationCode,
        });
    

        handleSignUpStep(nextStep);
      } catch (error) {
        console.log(error);
      }
    }
    

    // signUpUtils.ts
    async function handleSignUpStep( step: SignUpOutput["nextStep"]) {
    switch (step.signUpStep) {
      case "CONFIRM_SIGN_UP":
    

       // Redirect end-user to confirm-sign up screen.
    

      case "COMPLETE_AUTO_SIGN_IN":
    	   const codeDeliveryDetails = step.codeDeliveryDetails;
        if (codeDeliveryDetails) {
         // Redirect user to confirm-sign-up with link screen.
        }
        const signInOutput = await autoSignIn();
      // handle sign-in steps
    }

Functions

function confirmResetPassword

confirmResetPassword: (input: ConfirmResetPasswordInput) => Promise<void>;

  • Confirms the new password and verification code to reset the password.

    Parameter input

    The ConfirmResetPasswordInput object.

    Throws

    -ConfirmForgotPasswordException Thrown due to an invalid confirmation code or password.

    Throws

    -AuthValidationErrorCode Thrown due to an empty confirmation code, password or username.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function confirmSignIn

confirmSignIn: (input: ConfirmSignInInput) => Promise<ConfirmSignInOutput>;

  • Continues or completes the sign in process when required by the initial call to signIn.

    Parameter input

    The ConfirmSignInInput object

    Returns

    ConfirmSignInOutput

    Throws

    -VerifySoftwareTokenException: Thrown due to an invalid MFA token.

    Throws

    -RespondToAuthChallengeException: Thrown due to an invalid auth challenge response.

    Throws

    -AssociateSoftwareTokenException: Thrown due to a service error during the MFA setup process.

    Throws

    -AuthValidationErrorCode: Thrown when challengeResponse is not defined.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function confirmSignUp

confirmSignUp: (input: ConfirmSignUpInput) => Promise<ConfirmSignUpOutput>;

  • Confirms a new user account.

    Parameter input

    The ConfirmSignUpInput object.

    Returns

    ConfirmSignUpOutput

    Throws

    -ConfirmSignUpException Thrown due to an invalid confirmation code.

    Throws

    -AuthValidationErrorCode Thrown due to an empty confirmation code

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function confirmUserAttribute

confirmUserAttribute: (input: ConfirmUserAttributeInput) => Promise<void>;

  • Confirms a user attribute with the confirmation code.

    Parameter input

    The ConfirmUserAttributeInput object

    Throws

    -AuthValidationErrorCode - Thrown when confirmationCode is not defined.

    Throws

    -VerifyUserAttributeException - Thrown due to an invalid confirmation code or attribute.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function deleteUser

deleteUser: () => Promise<void>;

  • Deletes a user from the user pool while authenticated.

    Throws

    - DeleteUserException

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function deleteUserAttributes

deleteUserAttributes: (input: DeleteUserAttributesInput) => Promise<void>;

  • Deletes user attributes.

    Parameter input

    The DeleteUserAttributesInput object

    Throws

    -DeleteUserAttributesException - Thrown due to invalid attribute.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function fetchDevices

fetchDevices: () => Promise<FetchDevicesOutput>;

  • Fetches devices that have been remembered using rememberDevice for the currently authenticated user.

    Returns

    FetchDevicesOutput

    Throws

    ListDevicesException

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function fetchMFAPreference

fetchMFAPreference: () => Promise<FetchMFAPreferenceOutput>;

  • Fetches the preferred MFA setting and enabled MFA settings for the user.

    Returns

    FetchMFAPreferenceOutput

    Throws

    -GetUserException : error thrown when the service fails to fetch MFA preference and settings.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function fetchUserAttributes

fetchUserAttributes: () => Promise<FetchUserAttributesOutput>;

  • Fetches the current user attributes while authenticated.

    Throws

    - GetUserException - Cognito service errors thrown when the service is not able to get the user.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function forgetDevice

forgetDevice: (input?: ForgetDeviceInput) => Promise<void>;

  • Forget a remembered device while authenticated.

    Parameter input

    The ForgetDeviceInput object.

    Throws

    - ForgetDeviceException - Cognito service errors thrown when forgetting device with invalid device key

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function getCurrentUser

getCurrentUser: () => Promise<GetCurrentUserOutput>;

  • Gets the current user from the idToken.

    Parameter input

    The GetCurrentUserInput object.

    Returns

    GetCurrentUserOutput

    Throws

    - InitiateAuthException - Thrown when the service fails to refresh the tokens.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function rememberDevice

rememberDevice: () => Promise<void>;

  • Marks device as remembered while authenticated.

    Throws

    - UpdateDeviceStatusException - Cognito service errors thrown when setting device status to remembered using an invalid device key.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function resendSignUpCode

resendSignUpCode: (
    input: ResendSignUpCodeInput
) => Promise<ResendSignUpCodeOutput>;

  • Resend the confirmation code while signing up

    Parameter input

    The ResendSignUpCodeInput object

    Returns

    ResendSignUpCodeOutput

    Throws

    service: ResendConfirmationException - Cognito service errors thrown when resending the code.

    Throws

    validation: AuthValidationErrorCode - Validation errors thrown either username are not defined.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function resetPassword

resetPassword: (input: ResetPasswordInput) => Promise<ResetPasswordOutput>;

  • Resets a user's password.

    Parameter input

    The ResetPasswordInput object.

    Returns

    ResetPasswordOutput

    Throws

    -ForgotPasswordException Thrown due to an invalid confirmation code or password.

    Throws

    -AuthValidationErrorCode Thrown due to an empty username.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function sendUserAttributeVerificationCode

sendUserAttributeVerificationCode: (
    input: SendUserAttributeVerificationCodeInput
) => Promise<SendUserAttributeVerificationCodeOutput>;

  • Resends user's confirmation code when updating attributes while authenticated.

    Parameter input

    The SendUserAttributeVerificationCodeInput object

    Returns

    SendUserAttributeVerificationCodeOutput

    Throws

    - GetUserAttributeVerificationException

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function setUpTOTP

setUpTOTP: () => Promise<SetUpTOTPOutput>;

  • Sets up TOTP for the user.

    Returns

    SetUpTOTPOutput

    Throws

    -AssociateSoftwareTokenException Thrown if a service occurs while setting up TOTP.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function signIn

signIn: (input: SignInInput) => Promise<SignInOutput>;

  • Signs a user in

    Parameter input

    The SignInInput object

    Returns

    SignInOutput

    Throws

    service: InitiateAuthException, RespondToAuthChallengeException - Cognito service errors thrown during the sign-in process.

    Throws

    validation: AuthValidationErrorCode - Validation errors thrown when either username or password are not defined.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function signInWithRedirect

signInWithRedirect: (input?: SignInWithRedirectInput) => Promise<void>;

  • Signs in a user with OAuth. Redirects the application to an Identity Provider.

    Parameter input

    The SignInWithRedirectInput object, if empty it will redirect to Cognito HostedUI

    Throws

    AuthTokenConfigException - Thrown when the user pool config is invalid.

    Throws

    OAuthNotConfigureException - Thrown when the oauth config is invalid.

function signOut

signOut: (input?: SignOutInput) => Promise<void>;

  • Signs a user out

    Parameter input

    The SignOutInput object

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function signUp

signUp: (input: SignUpInput) => Promise<SignUpOutput>;

  • Creates a user

    Parameter input

    The SignUpInput object

    Returns

    SignUpOutput

    Throws

    service: SignUpException - Cognito service errors thrown during the sign-up process.

    Throws

    validation: AuthValidationErrorCode - Validation errors thrown either username or password are not defined.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function updateMFAPreference

updateMFAPreference: (input: UpdateMFAPreferenceInput) => Promise<void>;

  • Updates the MFA preference of the user.

    Parameter input

    The UpdateMFAPreferenceInput object.

    Throws

    -SetUserMFAPreferenceException - Service error thrown when the MFA preference cannot be updated.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function updatePassword

updatePassword: (input: UpdatePasswordInput) => Promise<void>;

  • Updates user's password while authenticated.

    Parameter input

    The UpdatePasswordInput object.

    Throws

    - ChangePasswordException - Cognito service errors thrown when updating a password.

    Throws

    - AuthValidationErrorCode - Validation errors thrown when oldPassword or newPassword are empty.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function updateUserAttribute

updateUserAttribute: (
    input: UpdateUserAttributeInput
) => Promise<UpdateUserAttributeOutput>;

  • Updates user's attribute while authenticated.

    Parameter input

    The UpdateUserAttributeInput object

    Returns

    UpdateUserAttributeOutput

    Throws

    - UpdateUserAttributesException

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function updateUserAttributes

updateUserAttributes: (
    input: UpdateUserAttributesInput
) => Promise<UpdateUserAttributesOutput>;

  • Updates user's attributes while authenticated.

    Parameter input

    The UpdateUserAttributesInput object

    Returns

    UpdateUserAttributesOutput

    Throws

    - UpdateUserAttributesException

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

function verifyTOTPSetup

verifyTOTPSetup: (input: VerifyTOTPSetupInput) => Promise<void>;

  • Verifies an OTP code retrieved from an associated authentication app.

    Parameter input

    The VerifyTOTPSetupInput

    Throws

    -VerifySoftwareTokenException: Thrown due to an invalid MFA token.

    Throws

    -AuthValidationErrorCode: Thrown when code is not defined.

    Throws

    AuthTokenConfigException - Thrown when the token provider config is invalid.

Classes

class AuthError

class AuthError extends AmplifyError {}

    constructor

    constructor(params: AmplifyErrorParams);

      Interfaces

      interface AuthUser

      interface AuthUser extends AWSAuthUser {}

      • Holds the user information along with the sign in details.

      property signInDetails

      signInDetails?: CognitoAuthSignInDetails;

        interface FetchMFAPreferenceOutput

        interface FetchMFAPreferenceOutput {}

          property enabled

          enabled?: AuthMFAType[];

            property preferred

            preferred?: AuthMFAType;

              interface UpdateMFAPreferenceInput

              interface UpdateMFAPreferenceInput {}

              • Input type for Cognito updateMFAPreference API.

              property sms

              sms?: MFAPreference;

                property totp

                totp?: MFAPreference;

                  Type Aliases

                  type CodeDeliveryDetails

                  type CodeDeliveryDetails<
                      CognitoUserAttributeKey extends UserAttributeKey = UserAttributeKey
                  > = AuthCodeDeliveryDetails<CognitoUserAttributeKey>;

                  • Holds data describing the dispatch of a confirmation code.

                  type ConfirmResetPasswordInput

                  type ConfirmResetPasswordInput =
                      AuthConfirmResetPasswordInput<ConfirmResetPasswordOptions>;

                  • Input type for Cognito confirmResetPassword API.

                  type ConfirmSignInInput

                  type ConfirmSignInInput = AuthConfirmSignInInput<ConfirmSignInOptions>;

                  • Input type for Cognito confirmSignIn API.

                  type ConfirmSignInOutput

                  type ConfirmSignInOutput = AuthSignInOutput;

                  • Output type for Cognito confirmSignIn API.

                  type ConfirmSignUpInput

                  type ConfirmSignUpInput = AuthConfirmSignUpInput<ConfirmSignUpOptions>;

                  • Input type for Cognito confirmSignUp API.

                  type ConfirmSignUpOutput

                  type ConfirmSignUpOutput = AuthSignUpOutput<AuthVerifiableAttributeKey>;

                  • Output type for Cognito confirmSignUp API.

                  type ConfirmUserAttributeInput

                  type ConfirmUserAttributeInput =
                      AuthConfirmUserAttributeInput<AuthVerifiableAttributeKey>;

                  • Input type for Cognito confirmUserAttribute API.

                  type DeleteUserAttributesInput

                  type DeleteUserAttributesInput = AuthDeleteUserAttributesInput<UserAttributeKey>;

                  • Input type for Cognito deleteUserAttributes API.

                  type FetchDevicesOutput

                  type FetchDevicesOutput = AWSAuthDevice[];

                  • Output type for Cognito fetchDevices API.

                  type FetchUserAttributesOutput

                  type FetchUserAttributesOutput = AuthUserAttributes<UserAttributeKey>;

                  • Output type for Cognito fetchUserAttributes API.

                  type ForgetDeviceInput

                  type ForgetDeviceInput = AuthForgetDeviceInput;

                  • Input type for Cognito forgetDevice API.

                  type GetCurrentUserOutput

                  type GetCurrentUserOutput = AuthUser;

                  • Output type for Cognito getCurrentUser API.

                  type ResendSignUpCodeInput

                  type ResendSignUpCodeInput = AuthResendSignUpCodeInput<ResendSignUpCodeOptions>;

                  • Input type for Cognito resendSignUpCode API.

                  type ResendSignUpCodeOutput

                  type ResendSignUpCodeOutput = AuthCodeDeliveryDetails<AuthVerifiableAttributeKey>;

                  • Output type for Cognito resendSignUpCode API.

                  type ResetPasswordInput

                  type ResetPasswordInput = AuthResetPasswordInput<ResetPasswordOptions>;

                  • Input type for Cognito resetPassword API.

                  type ResetPasswordOutput

                  type ResetPasswordOutput = AuthResetPasswordOutput<AuthVerifiableAttributeKey>;

                  • Output type for Cognito resetPassword API.

                  type SendUserAttributeVerificationCodeInput

                  type SendUserAttributeVerificationCodeInput =
                      AuthSendUserAttributeVerificationCodeInput<
                          VerifiableUserAttributeKey,
                          SendUserAttributeVerificationCodeOptions
                      >;

                  • Input type for Cognito sendUserAttributeVerificationCode API.

                  type SendUserAttributeVerificationCodeOutput

                  type SendUserAttributeVerificationCodeOutput =
                      AuthCodeDeliveryDetails<AuthVerifiableAttributeKey>;

                  • Output type for Cognito sendUserAttributeVerificationCode API.

                  type SetUpTOTPOutput

                  type SetUpTOTPOutput = AuthTOTPSetupDetails;

                  • Output type for Cognito setUpTOTP API.

                  type SignInInput

                  type SignInInput = AuthSignInInput<SignInOptions>;

                  • Input type for Cognito signIn API.

                  type SignInOutput

                  type SignInOutput = AuthSignInOutput;

                  • Output type for Cognito signIn API.

                  type SignInWithRedirectInput

                  type SignInWithRedirectInput = AuthSignInWithRedirectInput;

                  • Input type for Cognito signInWithRedirect API.

                  type SignOutInput

                  type SignOutInput = AuthSignOutInput;

                  • Input type for Cognito signOut API.

                  type SignUpInput

                  type SignUpInput = AuthSignUpInput<SignUpOptions<UserAttributeKey>>;

                  • Input type for Cognito signUp API.

                  type SignUpOutput

                  type SignUpOutput = AuthSignUpOutput<AuthVerifiableAttributeKey>;

                  • Output type for Cognito signUp API.

                  type UpdatePasswordInput

                  type UpdatePasswordInput = AuthUpdatePasswordInput;

                  • Input type for Cognito updatePassword API.

                  type UpdateUserAttributeInput

                  type UpdateUserAttributeInput = AuthUpdateUserAttributeInput<
                      UserAttributeKey,
                      UpdateUserAttributeOptions
                  >;

                  • Input type for Cognito updateUserAttribute API.

                  type UpdateUserAttributeOutput

                  type UpdateUserAttributeOutput = AuthUpdateUserAttributeOutput<UserAttributeKey>;

                  • Output type for Cognito updateUserAttribute API.

                  type UpdateUserAttributesInput

                  type UpdateUserAttributesInput = AuthUpdateUserAttributesInput<
                      UserAttributeKey,
                      UpdateUserAttributesOptions
                  >;

                  • Input type for Cognito updateUserAttributes API.

                  type UpdateUserAttributesOutput

                  type UpdateUserAttributesOutput = AuthUpdateUserAttributesOutput<UserAttributeKey>;

                  • Output type for Cognito updateUserAttributes API.

                  type UserAttributeKey

                  type UserAttributeKey = AuthStandardAttributeKey | CustomAttribute;

                  • The user attribute types available for Cognito.

                  type VerifiableUserAttributeKey

                  type VerifiableUserAttributeKey = AuthVerifiableAttributeKey;

                  • Verifiable user attribute types available for Cognito.

                  type VerifyTOTPSetupInput

                  type VerifyTOTPSetupInput = AuthVerifyTOTPSetupInput<VerifyTOTPSetupOptions>;

                  • Input type for Cognito verifyTOTPSetup API.

                  Package Files (31)

                  Dependencies (1)

                  Dev Dependencies (4)

                  Peer Dependencies (1)

                  Badge

                  To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                  You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@aws-amplify/auth.

                  • Markdown
                    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@aws-amplify/auth)
                  • HTML
                    <a href="https://www.jsdocs.io/package/@aws-amplify/auth"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>