Migrate from v5 to v6
The Auth
category has moved to a functional approach and named parameters in Amplify v6, so you will now import the functional API’s directly from the aws-amplify/auth
path as shown in the examples below and will need to pay close attention to the changes made to inputs and outputs. You can use the switcher on the API examples to see the differences between v5 and v6 implementations. (v6 is shown by default)
Auth.signUp
The overall input to Auth.signUp
is largely unchanged, but how the object is structured is slightly different: attributes
becomes userAttributes
, and userAttributes
and validationData
are now under an options
object. autoSignIn
can also now be a simple boolean value.
A major difference is that a CognitoUser
is no longer returned from signUp
. All Auth API’s now use the current signed in user information to perform operations, so sending and receiving CognitoUser
through every API is no longer required.
Also notice that userConfirmed
is no longer returned, and instead we return nextStep
. This follows a standardized format shared between the signUp
, signIn
, resetPassword
, and updateUserAttributes
flows, where additional authentication steps will be returned with any additional information included in the same object (in this case, codeDeliveryDetails
)
Input
V5
// Standardparams: SignUpParams { username: string; password: string; attributes?: object; validationData?: { [key: string]: string; } clientMetadata?: { [key: string]: string; }; autoSignIn?: { enabled: boolean; clientMetaData?: { [key: string]: string; }; validationData?: { [key: string]: string; } };}
// Legacyusername: stringpassword: stringemail: stringphone_number: string
V6
input: SignUpInput { username: string; password: string; options?: { userAttributes?: { [key: string]?: string; } validationData?: { [key: string]: string; }; clientMetadata?: { [key: string]: string; }; autoSignIn?: boolean | { authFlowType?: | 'USER_SRP_AUTH' | 'CUSTOM_WITH_SRP' | 'CUSTOM_WITHOUT_SRP' | 'USER_PASSWORD_AUTH'; clientMetadata?: { [key: string]: string; }; }; };}
Output
V5
ISignUpResult { user: CognitoUser; userConfirmed: boolean; userSub: string; codeDeliveryDetails: { AttributeName: string; DeliveryMedium: string; Destination: string; };}
V6
SignUpOutput { isSignUpComplete: boolean; userId?: string; nextStep: { signUpStep: | 'DONE' | 'CONFIRM_SIGN_UP' | 'COMPLETE_AUTO_SIGN_IN', codeDeliveryDetails: { // Not included when signUpStep is 'DONE' destination?: string; deliveryMedium?: | 'EMAIL' | 'SMS' | 'PHONE' | 'UNKNOWN'; attributeName?: UserAttributeKey; } };}
import { signUp } from 'aws-amplify/auth';
const handleSignUp = async ({ username, password, email, phone_number, validationData}) => { const { isSignUpComplete, userId, nextStep } = await signUp({ username, password, options: { userAttributes: { email, phone_number }, validationData } });}
import { Auth } from 'aws-amplify';
const handleSignUp = async ({ username, password, email, phone_number, validationData}) => { const { user } = await Auth.signUp({ username, password, attributes: { email, phone_number }, validationData });}
Auto Sign-in
import { autoSignIn, confirmSignUp, signUp} from 'aws-amplify/auth';
// 1. Sign Up with autoSignIn enabledconst handleSignUp = async ({ username, password, email, phone_number, validationData}) => { const { isSignUpComplete, userId, nextStep } = await signUp({ username, password, options: { userAttributes: { email, phone_number }, validationData, autoSignIn: true }, });}
// 2. Confirm Sign Upconst handleConfirmSignUp = async ({ username, confirmationCode}) => { const { isSignUpComplete, userId, nextStep } = await confirmSignUp({ username, confirmationCode });
// 3. Trigger autoSignIn event - will not be triggered automatically const { isSignedIn } = await autoSignIn();}
import { Auth, Hub } from 'aws-amplify';
// 1. Add listener for autoSignIn eventHub.listen('auth', ({ payload }) => { const { event } = payload; if (event === 'autoSignIn') { const confirmedUser = payload.data; } else if (event === 'autoSignIn_failure') { // redirect to sign in page }});
// 2. Sign Up with autoSignIn enabledconst handleSignUp = async ({ username, password, email, phone_number, validationData}) => { const { user } = await Auth.signUp({ username, password, attributes: { email, phone_number }, validationData, autoSignIn: { enabled: true } });}
// 3. Confirm Sign Up - this will trigger autoSignInconst handleConfirmSignUp = async ({ username, confirmationCode}) { await Auth.confirmSignUp(username, confirmationCode);}
Legacy
In the past, we've supported the ability to pass in username
, password
, email
, phone_number
as positional parameters instead of as named input parameters for Auth.signUp
for backwards compatibility with older versions of Amplify JavaScript. The following guide shows you how to migrate from that legacy call pattern for Auth.signUp
:
import { signUp } from 'aws-amplify/auth';
const handleSignUp = async ({ username, password, email, phone_number, validationData}) => { const { isSignUpComplete, userId, nextStep } = await signUp({ username, password, options: { userAttributes: { email, phone_number } } });}
import { Auth } from 'aws-amplify';
const handleSignUp = async ({ username, password, email, phone_number, validationData}) => { const { user } = await Auth.signUp( username, password, email, phone_number );}
Auth.confirmSignUp
In v6, confirmSignUp
now takes named parameters instead of positional parameters. You will send in an object with the properties username
, confirmationCode
, and options
. This API also returns an object containing an isSignUpComplete
flag, the userId
, and nextStep
for autoSignIn
use cases in v6.
Input
V5
username: stringcode: stringoptions?: ConfirmSignUpOptions { forceAliasCreation?: boolean; clientMetadata?: { [key: string]: string; };}
V6
input: ConfirmSignUpInput = { username: string; confirmationCode: string; options?: { clientMetadata?: { [key: string]: string; }; forceAliasCreation?: boolean; };}
Output
V5
'SUCCESS'
V6
type ConfirmSignUpOutput = { isSignUpComplete: boolean; userId?: string | undefined; nextStep: { signUpStep: | 'DONE' | 'CONFIRM_SIGN_UP' | 'COMPLETE_AUTO_SIGN_IN', codeDeliveryDetails: { // Not included when signUpStep is 'DONE' destination?: string; deliveryMedium?: | 'EMAIL' | 'SMS' | 'PHONE' | 'UNKNOWN'; attributeName?: UserAttributeKey; } };}
import { confirmSignUp } from 'aws-amplify/auth';
const handleConfirmSignUp = async ({ username, confirmationCode}) { const { isSignUpComplete, userId, nextStep } = await confirmSignUp({ username, confirmationCode });}
import { Auth } from 'aws-amplify';
const handleConfirmSignUp = async ({ username, confirmationCode}) { await Auth.confirmSignUp( username, confirmationCode );}
Force Alias Creation
import { confirmSignUp } from 'aws-amplify/auth';
const handleConfirmSignUp = async ({ username, confirmationCode}) { const { isSignUpComplete, userId, nextStep } = await confirmSignUp({ username, confirmationCode, options: { // default falsy (undefined) forceAliasCreation: true } });}
import { Auth } from 'aws-amplify';
const handleConfirmSignUp = async ({ username, confirmationCode}) { await Auth.confirmSignUp( username, confirmationCode, options: { // default true forceAliasCreation: false } );}
Auth.resendSignUp
In v6, resendSignUp
now takes named parameters instead of positional parameters. You will send in an object with the properties username
and options
, with clientMetadata
nested under options
for consistency across API's. The output has also been updated to match other API's, returning an object with destination
, deliveryMedium
, and attributeName
properties instead of the PascalCase CodeDeliveryDetails
.
Input
V5
username: stringclientMetadata?: ClientMetaData { [key: string]: string;}
V6
input: ResendSignUpCodeInput { username: string; options?: { clientMetadata?: { [key: string]: string; }; };}
Output
V5
{ CodeDeliveryDetails: { AttributeName: string, DeliveryMedium: string, Destination: string }}
V6
ResendSignUpCodeOutput { destination?: string; deliveryMedium?: | 'EMAIL' | 'SMS' | 'PHONE' | 'UNKNOWN'; attributeName?: AuthVerifiableAttributeKey;}
import { resendSignUpCode } from 'aws-amplify/auth';
const handleResendCode = async ({ username }) => { const { destination, deliveryMedium, attributeName } = await resendSignUpCode({ username });}
import { Auth } from 'aws-amplify';
const handleResendCode = async ({ username }) => { const { CodeDeliveryDetails } = await Auth.resendSignUp(username);}
Auth.signIn
The input to Auth.signIn
is largely unchanged in the v6 signIn
API, but how the object is structured is slightly different: clientMetadata
is now under an options
object that also includes an authFlowType
option if needed.
A major difference is that a CognitoUser
is no longer returned from signIn
. All Auth API’s now use the current signed in user information to perform operations, so sending and receiving CognitoUser
through every API is no longer required.
Also notice that challengeName
and challengeParam
(returned in v5 as additional properties on the CognitoUser
) are replaced in the output object by the nextStep
property. nextStep
includes signInStep
and possibly additional props depending on the step. See the Confirmation Required example for a detailed example of the new signIn
flow.
Input
V5
// StandardusernameOrSignInOpts: SignInOpts { username: string; password: string; validationData?: { [key: string]: any; };}pw?: undefinedclientMetadata?: ClientMetaData { [key: string]: string;}
// LegacyusernameOrSignInOpts: stringpw?: stringclientMetadata?: ClientMetaData { [key: string]: string;}
V6
input: SignInInput { username: string; password?: string; options?: { authFlowType?: | 'USER_SRP_AUTH' | 'CUSTOM_WITH_SRP' | 'CUSTOM_WITHOUT_SRP' | 'USER_PASSWORD_AUTH'; clientMetadata?: ClientMetaData { [key: string]: string; } };}
Output
V5
CognitoUser { challengeName?: string; challengeParam?: string; username: string; signInUserSession: { idToken: string; refreshToken: string; accessToken: string; clockDrift: number; } | null; authenticationFlowType: string;}
V6
type SignInOutput = { isSignedIn: boolean; nextStep: { signInStep: { | 'CONTINUE_SIGN_IN_WITH_MFA_SELECTION' | 'CONTINUE_SIGN_IN_WITH_TOTP_SETUP' | 'CONFIRM_SIGN_IN_WITH_SMS_CODE' | 'CONFIRM_SIGN_IN_WITH_TOTP_CODE' | 'CONFIRM_SIGN_IN_WITH_CUSTOM_CHALLENGE' | 'CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIRED' | 'CONFIRM_SIGN_UP' | 'RESET_PASSWORD' | 'DONE'; }, // May include additional props depending on the step }}
import { signIn } from 'aws-amplify/auth';
const handleSignIn = async ({ username, password}) => { const { isSignedIn, nextStep } = await signIn({ username, password });}
import { Auth } from 'aws-amplify';
const handleSignIn = async ({ username, password, validationData}) => { const user = await Auth.signIn({ username, password, validationData });}
Confirmation Required
import { confirmSignIn, signIn} from 'aws-amplify/auth';
const handleSignIn = async ({ username, password}) => { const { isSignedIn, nextStep } = await signIn({ username, password });
switch (nextStep.signInStep) { case 'CONFIRM_SIGN_IN_WITH_TOTP_CODE': case 'CONFIRM_SIGN_IN_WITH_SMS_CODE': // nextStep will contain codeDeliveryDetails when step is CONFIRM_SIGN_IN_WITH_SMS_CODE const { isSignedIn, nextStep } = await confirmSignIn({ challengeResponse: 'code' }); break; case 'CONFIRM_SIGN_IN_WITH_CUSTOM_CHALLENGE': const { additionalInfo } = nextStep; const { isSignedIn, nextStep } = await confirmSignIn({ challengeResponse: 'answer' }); break; case 'CONTINUE_SIGN_IN_WITH_TOTP_SETUP': // Note that calling setupTOTP is unnecessary in this scenario // totpSetupDetails are already returned with nextStep const { totpSetupDetails } = nextStep; const appName = 'my_app_name'; const setupUri = totpSetupDetails.getSetupUri(appName); // Open setupUri with an authenticator APP to retrieve an OTP code // Retrieve code from authenticator App const { isSignedIn, nextStep } = await confirmSignIn({ challengeResponse: 'code' }); break; case 'CONTINUE_SIGN_IN_WITH_MFA_SELECTION': const mfaType = 'SMS' // or TOTP const { isSignedIn, nextStep } = await confirmSignIn({ challengeResponse: mfaType});
// if confirmSignIn was called with 'SMS', then the next // step will be 'CONFIRM_SIGN_IN_WITH_SMS_CODE'. // However if 'TOTP' was used as input then 'CONFIRM_SIGN_IN_WITH_TOTP_CODE' // will be returned.
const otpCode = '123456' // code retrieved from authenticator App or cellphone const { isSignedIn, nextStep } = await confirmSignIn({ challengeResponse: otpCode}); break; case 'CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIRED': const { missingAttributes } = nextStep; const userAttributes = { ... };
const { isSignedIn, nextStep } = await confirmSignIn({ challengeResponse: 'newPassword', options: { userAttributes } }); break; case 'DONE': break; }}
import { Auth } from 'aws-amplify';
const handleSignIn = async ({ username, password, validationData}) => { const user = await Auth.signIn({ username, password });
if (user.challengeName) { switch(user.challengeName) { case 'SMS_MFA': case 'SOFTWARE_TOKEN': const confirmedUser = await Auth.confirmSignIn( user, 'code', user.challengeName ); break; case 'CUSTOM_CHALLENGE': const confirmedUser = await Auth.confirmSignIn( user, 'answer', user.challengeName ); break; case 'MFA_SETUP': const secretCode = await Auth.setupTOTP(user); // Proceed to Auth.confirmSignIn break; case 'SELECT_MFA_TYPE': const mfaType = 'SMS_MFA' // or 'SOFTWARE_TOKEN_MFA' // user returned from signIn user.sendMFASelectionAnswer(mfaType, { onFailure: (err) => { console.log(err); }, mfaRequired: (challengeName, parameters) => { // call confirmSignIn with the OTP code sent to your cellphone }, totpRequired: (challengeName, parameters) => { // call confirmSignIn with the OTP code retrieved from your authenticator App } }); break; case 'NEW_PASSWORD_REQUIRED': const { userAttributes, requiredAttributes } = user.challengeParams; const attributes = { ... };
const confirmedUser = await Auth.completeNewPassword( user, 'newPassword', attributes ); break; } }}
Legacy
In the past, we've supported the ability to pass in username
, password
as positional parameters instead of as named input parameters for Auth.signIn
for backwards compatibility with older versions of Amplify JavaScript. The following guide shows you how to migrate from that legacy call pattern for Auth.signIn
:
import { signIn } from 'aws-amplify/auth';
const username = 'username';const password = 'password';
const handleSignIn = async ({ username, password}) => { const { isSignedIn, nextStep } = await signIn({ username, password });}
import { Auth } from 'aws-amplify';
const handleSignIn = async ({ username, password}) => { const user = await Auth.resendSignUp( username, password );}
Auth.federatedSignIn
Auth.federatedSignIn
has become signInWithRedirect
in v6, but is otherwise similar. The provider
property accepts specific strings instead of an enum and also includes an option to send in a custom provider if you would like to use a provider not in the default list. For this use case you would pass an object containing the prop custom
to provider
instead of one of the predefined strings.
Input
V5
// Standardoptions?: FederatedSignInOptions { provider: { // enum Cognito = 'COGNITO', Google = 'Google', Facebook = 'Facebook', Amazon = 'LoginWithAmazon', Apple = 'SignInWithApple', }; customState?: string;}
// Custom Provideroptions?: FederatedSignInOptionsCustom { customProvider: string; customState?: string;}
// Legacyprovider: | 'google' | 'facebook' | 'amazon' | 'developer' | stringresponse: FederatedResponse { token: string; identity_id?: string; expires_at: number;}user: FederatedUser { name: string; email?: string; picture?: string;}
V6
input?: SignInWithRedirectInput { provider?: | 'Amazon' | 'Apple' | 'Facebook' | 'Google' | { custom: string; }; customState?: string; options?: { preferPrivateSession?: boolean; };}
Output
V5
// Only returns when FederatedResponse from Identity Pools is providedICredentials { accessKeyId: string; sessionToken: string; secretAccessKey: string; identityId: string; authenticated: boolean; expiration?: Date;}
V6
No output in v6
import { fetchAuthSession, signInWithRedirect} from 'aws-amplify/auth';
const handleSocialSignIn = async () => { await signInWithRedirect({ provider: 'Google' });}
import { Auth } from 'aws-amplify';
const handleSocialSignIn = async () => { await Auth.federatedSignIn({ provider: CognitoHostedUIIdentityProvider.Google });}
Custom Provider
import { signInWithRedirect } from 'aws-amplify/auth';
const handleSocialSignIn = () => { signInWithRedirect({ provider: { custom: 'SocialProvider' } });}
import { Auth } from 'aws-amplify';
const handleSocialSignIn = () => { Auth.federatedSignIn({ customProvider: 'SocialProvider' });}
Defaults
import { signInWithRedirect } from 'aws-amplify/auth';
const handleSocialSignIn = () => { signInWithRedirect();}
import { Auth } from 'aws-amplify';
const handleSocialSignIn = () => { Auth.federatedSignIn();}
Identity Pools - DEPRECATED
signInWithRedirect
does not allow you to pass a pre-authorized user and tokens for Amplify to consume. Follow this guide as an example of how to accomplish this in v6.
Auth.confirmSignIn
In v6, confirmSignIn
is now used not only for MFA confirmation, but also in place of Auth.completeNewPassword
and Auth.sendCustomChallengeAnswer
. The input no longer includes mfaType
and code
separately, but rather contains challengeAnswer
, which will allow you to pass the required information (including MFA type or a new password) as a value. See the Auth.signIn: Confirmation Required example for a detailed example of the new signIn
flow.
Another major difference is that CognitoUser
is no longer required as an input parameter or returned from confirmSignIn
. All Auth API’s now use the current signed in user information to perform operations, so sending and receiving CognitoUser
through every API is no longer required.
Also notice that challengeName
and challengeParam
(returned in v5 as additional properties on the CognitoUser
) are replaced in the output object by the nextStep
property. nextStep
includes signInStep
and possibly additional props depending on the step.
Input
V5
user: CognitoUsercode: stringmfaType?: 'SMS_MFA' | 'SOFTWARE_TOKEN_MFA' | nullclientMetadata?: ClientMetaData { [key: string]: string;}
V6
input: ConfirmSignInInput { challengeResponse: string; options?: { userAttributes?: AuthUserAttributes; clientMetadata?: ClientMetaData { [key: string]: string; } friendlyDeviceName?: string; };}
Output
V5
CognitoUser { challengeName?: string; challengeParam?: string; username: string; signInUserSession: { idToken: string; refreshToken: string; accessToken: string; clockDrift: number; } | null; authenticationFlowType: string;}
V6
ConfirmSignInOutput { isSignedIn: boolean; nextStep: { signInStep: { | 'CONTINUE_SIGN_IN_WITH_MFA_SELECTION' | 'CONTINUE_SIGN_IN_WITH_TOTP_SETUP' | 'CONFIRM_SIGN_IN_WITH_SMS_CODE' | 'CONFIRM_SIGN_IN_WITH_TOTP_CODE' | 'CONFIRM_SIGN_IN_WITH_CUSTOM_CHALLENGE' | 'CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIRED' | 'CONFIRM_SIGN_UP' | 'RESET_PASSWORD' | 'DONE'; }, // May include additional props depending on the step }}
import { confirmSignIn } from 'aws-amplify/auth';
const handleConfirmSignIn = async ({ challengeResponse }) => { const { isSignedIn, nextStep } = await confirmSignIn({ challengeResponse });}
import { Auth } from 'aws-amplify';
const handleConfirmSignIn = async ({ user, code, mfaType}) => { const user = await Auth.confirmSignIn( user, code, mfaType );}
Auth.setupTOTP
There is now no input for setupTOTP
in v6. All Auth API’s in v6 use the current signed in user information to perform operations, so sending and receiving CognitoUser
through every API is no longer required.
The output is no longer just a string representing the secret code, but an object with a property called sharedSecret
and the method getSetupUri
that builds and returns the setup uri needed for TOTP authentication based on that secret.
Input
V5
user: CognitoUser
V6
No input in v6
Output
V5
string // secretCode
V6
SetUpTOTPOutput { sharedSecret: string; getSetupUri: (appName: string, accountName?: string | undefined) => URL;}
import { setUpTOTP } from 'aws-amplify/auth';
const handleSetupTOTP = async () => { const output = await setUpTOTP(); const secretCode = output.sharedSecret; const setupUri = output.getSetupUri('sample-app');}
import { Auth } from 'aws-amplify';
const handleSetupTOTP = async ({ user }) => { const secretCode = await Auth.setupTOTP(user); const setupUri = `otpauth://totp/AWSCognito:${user}?secret=${secretCode}&issuer=sample-app`;}
Auth.verifyTotpToken
In v6, Auth.verifyTotpToken
has become verifyTOTPSetup
, and the input has changed: you no longer need to send in a CognitoUser and the challengeAnswer
parameter has become the code
property in the input object. The method also no longer returns a CognitoSession: see Auth.currentSession for details on how you would retrieve the current session details returned in v5.
Input
V5
user: CognitoUserchallengeAnswer: string
V6
input: VerifyTOTPSetupInput { code: string; options?: { friendlyDeviceName?: string; }}
Output
V5
CognitoUserSession { idToken: string; refreshToken: string; accessToken: string; clockDrift: number;}
V6
No output in v6
import { verifyTOTPSetup } from 'aws-amplify/auth';
const handleVerifyTOTP = async ({ code }) => { await verifyTOTPSetup({ code , options });}
import { Auth } from 'aws-amplify';
const handleVerifyTOTP = async ({ user, code }) => { const userSession = await Auth.verifyTotpToken(user, code);}
Auth.completeNewPassword (DEPRECATED)
This API has been deprecated: existing use cases can be migrated to the confirmSignIn
API, which returns an object with nextStep
instead of a CognitoUser
with challengeName
and challengeParam
. For a comprehensive example on the full v6 signIn
flow and how to respond to each nextStep
value, see the Auth.signIn Confirmation Required example.
Input
V5
user: CognitoUserpassword: stringrequiredAttributes?: anyclientMetadata?: ClientMetaData { [key: string]: string;}
V6
input: ConfirmSignInInput { challengeResponse: string; options?: { userAttributes?: AuthUserAttributes; clientMetadata?: ClientMetaData { [key: string]: string; } friendlyDeviceName?: string; };}
Output
V5
CognitoUser { challengeName?: string; challengeParam?: string; username: string; signInUserSession: { idToken: string; refreshToken: string; accessToken: string; clockDrift: number; } | null; authenticationFlowType: string;}
V6
ConfirmSignInOutput { isSignedIn: boolean; nextStep: { // See Auth.signIn Example 2 for more details on nextStep types signInStep: { | 'CONTINUE_SIGN_IN_WITH_MFA_SELECTION' | 'CONTINUE_SIGN_IN_WITH_TOTP_SETUP' | 'CONFIRM_SIGN_IN_WITH_SMS_CODE' | 'CONFIRM_SIGN_IN_WITH_TOTP_CODE' | 'CONFIRM_SIGN_IN_WITH_CUSTOM_CHALLENGE' | 'CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIRED' | 'CONFIRM_SIGN_UP' | 'RESET_PASSWORD' | 'DONE'; }, // May include additional props depending on the step }}
import { confirmSignIn } from 'aws-amplify/auth';
const handleUpdatePassword = async ({ newPassword }) => { const { isSignedIn, nextStep } = await confirmSignIn({ challengeResponse: newPassword });}
import { Auth } from 'aws-amplify';
const handleUpdatePassword = async ({ user, newPassword, attributes}) => { const user = await Auth.completeNewPassword( user, newPassword, attributes );}
Auth.sendCustomChallengeAnswer (DEPRECATED)
This API has been deprecated: existing use cases can be migrated to the confirmSignIn
API, which returns an object with nextStep
instead of a CognitoUser
with challengeName
and challengeParam
. For a comprehensive example on the full v6 signIn flow and how to respond to each nextStep
value, see the Auth.signIn Confirmation Required example.
Input
V5
user: CognitoUserchallengeResponses: stringclientMetadata?: ClientMetaData { [key: string]: string;}
V6
input: ConfirmSignInInput { challengeResponse: string; options?: { userAttributes?: AuthUserAttributes; clientMetadata?: ClientMetaData { [key: string]: string; } friendlyDeviceName?: string; };}
Output
V5
CognitoUser { challengeName?: string; challengeParam?: string; username: string; signInUserSession: { idToken: string; refreshToken: string; accessToken: string; clockDrift: number; } | null; authenticationFlowType: string;}
V6
ConfirmSignInOutput { isSignedIn: boolean; nextStep: { // See Auth.signIn Example 2 for more details on nextStep types signInStep: { | 'CONTINUE_SIGN_IN_WITH_MFA_SELECTION' | 'CONTINUE_SIGN_IN_WITH_TOTP_SETUP' | 'CONFIRM_SIGN_IN_WITH_SMS_CODE' | 'CONFIRM_SIGN_IN_WITH_TOTP_CODE' | 'CONFIRM_SIGN_IN_WITH_CUSTOM_CHALLENGE' | 'CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIRED' | 'CONFIRM_SIGN_UP' | 'RESET_PASSWORD' | 'DONE'; }, // May include additional props depending on the step }}
import { confirmSignIn } from 'aws-amplify/auth';
const handleConfirmSignIn = async ({ challengeResponse }) => { const { isSignedIn, nextStep } = await confirmSignIn({ challengeResponse });}
import { Auth } from 'aws-amplify';
const handleConfirmSignIn = async ({ user, code}) => { const user = await Auth.confirmSignIn( user, code );}
Auth.getPreferredMFA
In v6, Auth.getPreferredMFA
has become the fetchMFAPreference
API. This API no longer accepts a CognitoUser
: all Auth API’s now use the current signed in user information to perform operations, so sending and receiving CognitoUser
through every API is no longer required. There is also no longer a bypassCache option in v6, as fetchMFAPreference
will always make a call to the server.
The return value in v6 is no longer just a string, but is now an object containing an enabled
array and a preferred
string.
Cognito can have multiple enabled
MFA options: as of now, it only supports TOTP
and SMS
. An MFA option is considered to be enabled
when it was previously setup. For instance, the TOTP
set up can be done during the sign-in process when the signIn
API returns the CONTINUE_SIGN_IN_WITH_TOTP_SETUP
step. It can also be set up when the user is authenticated by calling setupTOTP
and verifyTOTPSetup
.
In addition, Cognito only allows 1 option to be preferred
. This can be achieved by calling the updateMFAPreference
API.
Input
V5
user: CognitoUserparams?: GetPreferredMFAOpts { bypassCache: boolean;}
V6
No input in v6
Output
V5
'SMS' | 'TOTP'
V6
FetchMFAPreferenceOutput: { enabled?: ('SMS' | 'TOTP')[]; preferred?: 'SMS' | 'TOTP';}
import { fetchMFAPreference } from 'aws-amplify/auth';
const getPreferredMFA = async () => { const { preferred } = await fetchMFAPreference(); return preferred;}
import { Auth } from 'aws-amplify';
const getPreferredMFA = async ({ user }) => { const preferredMFA = await Auth.getPreferredMFA(user); return preferredMFA;}
Auth.setPreferredMFA
In v6, Auth.setPreferredMFA
has been replaced by updateMFAPreference
, which can also be used to enable and disable MFA methods. This method accepts an object with the properties sms
and mfa
, each of which can be set to ENABLED
, DISABLED
, PREFERRED
, and NOT_PREFERRED
.
Input
V5
user: CognitoUsermfaMethod: | 'TOTP' | 'SMS' | 'NOMFA' | 'SMS_MFA' | 'SOFTWARE_TOKEN_MFA'
V6
input: UpdateMFAPreferenceInput { sms?: | 'ENABLED' | 'DISABLED' | 'PREFERRED' | 'NOT_PREFERRED' mfa?: | 'ENABLED' | 'DISABLED' | 'PREFERRED' | 'NOT_PREFERRED'}
Output
V5
'No change for mfa type' | 'SUCCESS'
V6
No output in v6
import { updateMFAPreference } from 'aws-amplify/auth';
const handleSetPreferredMFA = async () => { await updateMFAPreference({ totp: 'PREFERRED' });}
import { Auth } from 'aws-amplify';
const handleSetPreferredMFA = async ({ user }) => { await Auth.setPreferredMFA(user, 'TOTP');}
Auth.getMFAOptions (DEPRECATED)
This API has been deprecated and results apply only to SMS MFA configurations: existing use cases can be migrated to fetchMFAPreference
(see Auth.getPreferredMFA), which will apply to both SMS and TOTP configurations.
Input
V5
user: CognitoUser
V6
No input in v6
Output
V5
MFAOption[]: { DeliveryMedium: 'SMS' | ~~'EMAIL'~~; AttributeName: string;}[]
V6
FetchMFAPreferenceOutput: { enabled?: ('SMS' | 'TOTP')[]; preferred?: 'SMS' | 'TOTP';}
import { fetchMFAPreference } from 'aws-amplify/auth';
const getEnabledMFAOptions = async () => { const { enabled } = await fetchMFAPreference(); return enabled;}
import { Auth } from 'aws-amplify';
const getEnabledMFAOptions = async ({ user }) => { const mfaOptions = await Auth.getMFAOptions(user); const enabled: string[] = []; for(let option of mfaOptions) { enabled.push(option.DeliverMedium); } return enabled;}
Auth.signOut
The signOut
API has not changed from v5 to v6 other than that it is now a functional API.
Input
V5
opts?: SignOutOpts { global?: boolean;}
V6
input?: SignOutInput { global: boolean;}
import { signOut } from 'aws-amplify/auth';
const handleSignOut = async () => { await signOut();}
import { Auth } from 'aws-amplify';
const handleSignOut = async () => { await Auth.signOut();}
Auth.changePassword
The Auth.changePassword
API has become updatePassword
in v6. It now accepts named parameters as input instead of positional parameters. The input is now an object containing oldPassword
and newPassword
.
CognitoUser
is not required input for updatePassword
. All Auth API’s now use the current signed in user information to perform operations, so sending and receiving CognitoUser
through every API is no longer required.
Input
V5
user: CognitoUseroldPassword: stringnewPassword: stringclientMetadata?: ClientMetaData { [key: string]: string}
V6
input: UpdatePasswordInput { oldPassword: string; newPassword: string;}
Output
V5
'SUCCESS'
V6
No output in v6
import { updatePassword } from 'aws-amplify/auth';
const handleChangePassword = async ({ oldPassword, newPassword}) => { await updatePassword({ oldPassword, newPassword });}
import { Auth } from 'aws-amplify';
const handleChangePassword = async ({ user, oldPassword, newPassword}) => { await Auth.changePassword( user, oldPassword, newPassword );}
Auth.forgotPassword
In v6, the Auth.forgotPassword
API has become resetPassword
. It uses named parameters instead of positional, so the input will now be an object with username
and options
(clientMetadata
can be passed in options
if needed).
Input
V5
username: stringclientMetadata?: ClientMetaData { [key: string]: string;}
V6
input: ResetPasswordInput { username: string; options?: { clientMetadata?: { [key: string]: string; }; };}
Output
V5
{ CodeDeliveryDetails: { AttributeName: string; DeliveryMedium: string; Destination: string; }}
V6
ResetPasswordOutput { isPasswordReset: boolean; nextStep: { resetPasswordStep: | 'CONFIRM_RESET_PASSWORD_WITH_CODE' | 'DONE'; additionalInfo?: { [key: string]: string; }; codeDeliveryDetails: { destination?: string; deliveryMedium?: | 'EMAIL' | 'SMS' | 'PHONE' | 'UNKNOWN'; attributeName?: 'email' | 'phone_number'; }; };}
import { resetPassword } from 'aws-amplify/auth';
const handleResetPassword = async ({ username, clientMetadata}) => { const result = await resetPassword({ username, options: { clientMetadata } }); const { attributeName, deliveryMedium, destination } = result.nextStep.codeDeliveryDetails;}
import { Auth } from 'aws-amplify';
const handleResetPassword = async ({ username, clientMetadata}) => { const result = await Auth.forgotPassword( username, clientMetadata );
const { AttributeName, DeliveryMedium, Destination } = result.CodeDeliveryDetails;}
Auth.forgotPasswordSubmit
Auth.forgotPasswordSubmit
has become confirmResetPassword
and takes named parameters instead of positional parameters. The expected input is now an object containing username
, newPassword
, confirmationCode
, and options
. If needed, customMetadata
can be sent through the options
property.
Input
V5
username: stringcode: stringpassword: stringclientMetadata?: ClientMetaData { [key: string]: string;};
V6
input: ConfirmResetPasswordInput { username: string; newPassword: string; confirmationCode: string; options?: { clientMetadata?: { [key: string]: string; }; };}
Output
V5
'SUCCESS'
V6
No output in v6
import { confirmResetPassword } from 'aws-amplify/auth';
const handleConfirmResetPassword = async ({ username, newPassword, confirmationCode, clientMetadata}) => { await confirmResetPassword: ({ username, newPassword, confirmationCode, options: { clientMetadata } });}
import { Auth } from 'aws-amplify';
const handleConfirmResetPassword = async ({ username, newPassword, confirmationCode, clientMetadata}) => { await Auth.forgotPasswordSubmit( username, confirmationCode, newPassword, clientMetadata );}
Auth.deleteUser
The deleteUser
API has not changed from v5 to v6 other than that it is now a functional API.
import { deleteUser } from 'aws-amplify/auth';
const handleDeleteAttributes = async ({ attributes }) => { await deleteUser();}
import { Auth } from 'aws-amplify';
const handleDeleteUser = async () => { await Auth.deleteUser();}
Auth.currentAuthenticatedUser (DEPRECATED)
This API has been deprecated: existing use cases can be migrated to a combination of the getCurrentUser
and fetchAuthSession
API's.
Also note that we no longer return refreshToken
or clockDrift
with the AuthSession
. These values are used under the hood to refresh/validate the user session.
Input
V5
params?: CurrentUserOpts { bypassCache: boolean;}
V6
// fetchAuthSessionoptions?: FetchAuthSessionOptions { forceRefresh?: boolean;}
Output
V5
CognitoUser { username: string; signInUserSession: { idToken: string; refreshToken: string; accessToken: string; clockDrift: number; } | null; authenticationFlowType: string;}
V6
// getCurrentUserGetCurrentUserOutput: { username: string; userId: string; signInDetails?: { loginId?: string; authFlowType?: | 'USER_SRP_AUTH' | 'CUSTOM_WITH_SRP' | 'CUSTOM_WITHOUT_SRP' | 'USER_PASSWORD_AUTH';; };}
// fetchAuthSessionAuthSession { tokens?: { idToken?: JWT; accessToken: JWT; }; credentials?: { accessKeyId: string; secretAccessKey: string; sessionToken?: string; expiration?: Date; }; identityId?: string; userSub?: string;}
import { fetchAuthSession, getCurrentUser} from 'aws-amplify/auth';
const getAuthenticatedUser = async () => { const { username, signInDetails } = await getCurrentUser();
const { tokens: session } = await fetchAuthSession();
// Note that session will no longer contain refreshToken and clockDrift return { username, session, authenticationFlowType: signInDetails.authFlowType };}
import { Auth } from 'aws-amplify';
const getAuthenticatedUser = async () => { const { username, signInUserSession: session, authenticationFlowType } = await Auth.currentAuthenticatedUser();
return { username, session, authenticationFlowType };}
Auth.currentUserPoolUser (DEPRECATED)
This API has been deprecated: existing use cases can be migrated to a combination of the getCurrentUser
and fetchAuthSession
API's.
Also note that we no longer return refreshToken
or clockDrift
with the AuthSession
. These values are used under the hood to refresh/validate the user session.
Input
V5
params?: CurrentUserOpts { bypassCache: boolean;}
V6
// fetchAuthSessionoptions?: FetchAuthSessionOptions { forceRefresh?: boolean;}
Output
V5
CognitoUser { username: string; signInUserSession: { idToken: string; refreshToken: string; accessToken: string; clockDrift: number; } | null; authenticationFlowType: string;}
V6
// getCurrentUserGetCurrentUserOutput: { username: string; userId: string; signInDetails?: { loginId?: string; authFlowType?: | 'USER_SRP_AUTH' | 'CUSTOM_WITH_SRP' | 'CUSTOM_WITHOUT_SRP' | 'USER_PASSWORD_AUTH';; };}
// fetchAuthSessionAuthSession { tokens?: { idToken?: JWT; accessToken: JWT; }; credentials?: { accessKeyId: string; secretAccessKey: string; sessionToken?: string; expiration?: Date; }; identityId?: string; userSub?: string;}
import { fetchAuthSession, getCurrentUser} from 'aws-amplify/auth';
const getAuthenticatedUser = async () => { const { username, authFlowType: authenticationFlowType } = await getCurrentUser();
// Note that session will no longer contain refreshToken and clockDrift const { tokens: session } = await fetchAuthSession();}
import { Auth } from 'aws-amplify';
const getAuthenticatedUser = async () => { const { username, signInUserSession: session, authenticationFlowType } = await Auth.currentUserPoolUser();}
Auth.currentSession
Auth.currentSession
has become fetchAuthSession
in v6. You can now optionally send an object with a forceRefresh
flag as input.
Note that we no longer return refreshToken
or clockDrift
with the AuthSession
. These values are used under the hood to refresh/validate the user session.
Input
V5
No input in v5
V6
options?: FetchAuthSessionOptions { forceRefresh?: boolean;}
Output
V5
CognitoUserSession { idToken: string; refreshToken: string; accessToken: string; clockDrift: number;}
V6
AuthSession { tokens?: { idToken?: JWT; accessToken: JWT; }; credentials?: { accessKeyId: string; secretAccessKey: string; sessionToken?: string; expiration?: Date; }; identityId?: string; userSub?: string;}
import { fetchAuthSession } from 'aws-amplify/auth';
const getSession = async () => { const { tokens, credentials, identityId, userSub } = await fetchAuthSession();
const { idToken, accessToken } = tokens;}
import { Auth } from 'aws-amplify';
const getSession = async () => { const { idToken, refreshToken, accessToken, clockDrift } = await Auth.currentSession();}
Auth.userSession (DEPRECATED)
Note: we no longer return refreshToken
or clockDrift
with the AuthSession
. These values are used under the hood to refresh/validate the user session
Auth.userSession
is deprecated in favor of fetchUserSession
as all Auth API’s now use the current signed in user information to perform operations, so sending and receiving CognitoUser
through every API is no longer required.
Input
V5
user: CognitoUser
V6
options?: FetchAuthSessionOptions { forceRefresh?: boolean;}
Output
V5
CognitoUserSession { idToken: string; refreshToken: string; accessToken: string; clockDrift: number;}
V6
AuthSession { tokens?: { idToken?: JWT; accessToken: JWT; }; credentials?: { accessKeyId: string; secretAccessKey: string; sessionToken?: string; expiration?: Date; }; identityId?: string; userSub?: string;}
import { fetchAuthSession } from 'aws-amplify/auth';
const getSession = async () => { const { tokens, credentials, identityId, userSub } = await fetchAuthSession();
const { idToken, accessToken } = tokens;}
import { Auth } from 'aws-amplify';