Password Reset Flow
This feature is in Early Access. For more information on the Auth0 product release stages, review Product Release Stages.
The Password Reset Flow runs during the password reset process when a user completes the first challenge, typically a link to the user's email, but before a new password is set. You can use this flow to challenge a user with an additional multi-factor authentication (MFA) factor or to redirect the user to an external site, such as a third-party verifier.
After verification, users can provide the new password for their account.
Actions in this flow are blocking (synchronous), which means they execute as part of a trigger's process and will prevent the rest of the Auth0 pipeline from running until the Action is complete.
Triggers
PostChallenge
The post-challenge trigger is a function that executes after a user completes the first password reset challenge, typically an email magic link.
References
Event object: Provides contextual information about a single user logging in via Auth0.
API object: Provides methods for changing the behavior of the flow.
Common use cases
Secure password reset with additional MFA factors
A password-reset / post-challenge Actions can issue an MFA challenge after the user completes the first challenge. For example, you can issue a WebAuthn-based challenge as a secondary factor if your tenant has WebAuthN enabled as a factor.
/**@type {PasswordResetPostChallengeAction}**/
module.exports.onExecutePostChallenge = async (event, api) => {
const enrolledFactors = event.user.enrolledFactors.map((x) => ({
type: x.type
}));
api.authentication.challengeWith({ type: 'webauthn-roaming' }, { additionalFactors: enrolledFactors });
};Was this helpful?
Redirect users to a third-party application
In addition to an MFA challenge, you can also try adding a redirect in the custom Action, for example, to a third-party verifier or risk assessor.
/** @type {PasswordResetPostChallengeAction}
* This sample action redirects the user to an example app
* and then continues the action after the redirect to challenge
* the user with an MFA factor
*/
module.exports.onExecutePostChallenge = async (event, api) => {
// Send the user to https://my-app.example.com
api.redirect.sendUserTo('https://my-app.example.com');
};
module.exports.onContinuePostChallenge = async (event, api) => {
const enrolledFactors = event.user.enrolledFactors.map((x) => ({
type: x.type
}));
// Challenge the user with email otp OR another enrolled factor
api.authentication.challengeWith({ type: 'email' }, { additionalFactors: enrolledFactors });
// Example of how to challenge the user with multiple options
// in this case email otp OR sms otp
// api.authentication.challengeWithAny([{ type: 'email' }, { type: 'sms' }]);
};Was this helpful?
The Actions pipeline is not active while Auth0 redirects the user. Once the user continues the Auth0 login process, the Actions pipeline resumes. Actions that were executed prior to the redirect are not executed again. To learn more, review Redirect with Actions.
Continue the password reset journey
After an application finishes performing additional checks or additional steps for the user, you can resume the password reset journey by redirecting the user to /continue/password-reset. This redirect can be used with both third-party integrations and custom applications.
Example
/**
* Handler that will be called during the execution of a Password Reset / Post Challenge Flow.
*
* @param {Event} event - Details about the post challenge request.
* @param {PasswordResetPostChallengeAPI} api - Interface whose methods can be used to change the behavior of the post challenge flow.
*/
exports.onExecutePostChallenge = async (event, api) => {
const YOUR_AUTH0_DOMAIN = event.request.hostname
// Craft a signed session token
const token = api.redirect.encodeToken({
secret: event.secrets.MY_REDIRECT_SECRET,
expiresInSeconds: 60,
payload: {
// Custom claims to be added to the token
email: event.user.email,
externalUserId: 1234,
continue_uri: `https://${YOUR_AUTH0_DOMAIN}/continue/reset-password`,
favorite_color: 'red',
},
});
// Send the user to https://my-app.exampleco.com along
// with a `session_token` query string param
api.redirect.sendUserTo(`https://my-app.exampleco.com`, {
query: { session_token: token }
});
};
exports.onContinuePostChallenge = async (event, api) => {
const payload = api.redirect.validateToken({
secret: event.secrets.MY_REDIRECT_SECRET,
tokenParameterName: 'session_token',
});
// use the data encoded in the token, such as:
if(payload.favorite_color === 'red'){
api.access.deny('No entry')
}
}Was this helpful?
To learn more about redirect Actions and how you can implement the custom application, review Redirect with Actions. When using redirects to resume the password reset flow, ensure you use /continue/password-reset rather than /continue to avoid any errors.