@aws-amplify/auth

  • Version 6.0.18
  • 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

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;

        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 FetchMFAPreferenceOutput

        type FetchMFAPreferenceOutput = {
        enabled?: AuthMFAType[];
        preferred?: AuthMFAType;
        };

          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 UpdateMFAPreferenceInput

          type UpdateMFAPreferenceInput = {
          sms?: MFAPreference;
          totp?: MFAPreference;
          };
          • Input type for Cognito updateMFAPreference 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>