Logo for jsDocs.io

@aws-amplify/auth

  • Version 6.12.4
  • Published
  • 3.14 MB
  • 3 dependencies
  • 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 associateWebAuthnCredential

associateWebAuthnCredential: () => Promise<void>;

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 deleteWebAuthnCredential

deleteWebAuthnCredential: (
    input: DeleteWebAuthnCredentialInput
) => Promise<void>;

  • Delete a registered credential for an authenticated user by credentialId

    Parameter input

    The delete input parameters including the credentialId

    Returns

    Promise

    Throws

    - AuthError: - Thrown when user is unauthenticated

    Throws

    - DeleteWebAuthnCredentialException - Thrown due to a service error when deleting a WebAuthn credential

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 listWebAuthnCredentials

listWebAuthnCredentials: (
    input?: ListWebAuthnCredentialsInput
) => Promise<ListWebAuthnCredentialsOutput>;

  • Lists registered credentials for an authenticated user

    Parameter input

    The list input parameters including page size and next token.

    Returns

    Promise

    Throws

    - AuthError: - Thrown when user is unauthenticated

    Throws

    - ListWebAuthnCredentialsException - Thrown due to a service error when listing WebAuthn credentials

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 AuthWebAuthnCredential

        interface AuthWebAuthnCredential {}

        • Shape of a WebAuthn credential

        property authenticatorAttachment

        authenticatorAttachment?: string;

          property authenticatorTransports

          authenticatorTransports: string[] | undefined;

            property createdAt

            createdAt: Date | undefined;

              property credentialId

              credentialId: string | undefined;

                property friendlyCredentialName

                friendlyCredentialName: string | undefined;

                  property relyingPartyId

                  relyingPartyId: string | undefined;

                    interface DeleteWebAuthnCredentialInput

                    interface DeleteWebAuthnCredentialInput {}

                      property credentialId

                      credentialId: string;

                        interface FetchMFAPreferenceOutput

                        interface FetchMFAPreferenceOutput {}

                          property enabled

                          enabled?: AuthMFAType[];

                            property preferred

                            preferred?: AuthMFAType;

                              interface ListWebAuthnCredentialsInput

                              interface ListWebAuthnCredentialsInput {}

                              • Input type for Cognito listWebAuthnCredentials API.

                              property nextToken

                              nextToken?: string;

                                property pageSize

                                pageSize?: number;

                                  interface ListWebAuthnCredentialsOutput

                                  interface ListWebAuthnCredentialsOutput {}

                                  • Output type for Cognito listWebAuthnCredentials API.

                                  property credentials

                                  credentials: AuthWebAuthnCredential[];

                                    property nextToken

                                    nextToken?: string;

                                      interface UpdateMFAPreferenceInput

                                      interface UpdateMFAPreferenceInput {}

                                      • Input type for Cognito updateMFAPreference API.

                                      property email

                                      email?: MFAPreference;

                                        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 (37)

                                            Dependencies (3)

                                            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>