Suspend journeys with "magic links"
You can use the Email Suspend Node within your journeys to support a number of flows, including verifying a user’s email address, building a "forgot password" flow or using an email address for multifactor authentication.
The node suspends the journey until the user clicks a link—referred to as a magic link--in their email. This link contains a generated unique code that can continue the suspended journey.
This page shows how to configure the Ping (ForgeRock) Login Widget to take advantage of this feature.
Configure the authentication server
-
Add the Email Suspend Node to the journey to suspend it until the user continues the journey from the link found in their email.
Figure 1. Insert the Email Suspend Node into your journey -
Configure the External Login Page URL property in the Access Management native console to match your custom app’s URL. This ensures the magic links are able to redirect users to your app to resume the journey. If not specified, the default behavior is to route users to the login page.
Figure 2. Configure external login URL in the PingAM native console -
When the Ping (ForgeRock) Login Widget encounters the Email Suspend Node, it renders the string configured in the Email Suspend Message property configured in the node. The user is not able to continue the journey until they click the link emailed to them.
Handle suspend IDs in your app
When your app handles a magic link, it needs to recognize it as a special condition and provide the Ping (ForgeRock) Login Widget with the full URL that the user clicked in their email.
Return this URL, including all query parameters, to the server as the value of the resumeUrl parameter:
import { journey } from '@forgerock/login-widget';
const journeyEvents = journey();
const url = new URL(location.href);
const suspendedId = url.searchParams.get('suspendedId');
if (suspendedId) {
journeyEvents.start({ resumeUrl: location.href });
}The location.href value includes all query parameters included in the magic link.
Without all the query parameters, the Ping (ForgeRock) Login Widget might not be able to rehydrate the journey and continue as needed.