ForgeRock Developer Experience

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 ForgeRock Login Widget to take advantage of this feature.

Configure the authentication server

  1. Add the Email Suspend Node to the journey to suspend it until the user continues the journey from the link found in their email.

    how to magic links tree en
    Figure 1. Insert the Email Suspend Node into your journey
  2. 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 ForgeRock login page.

    how to magic links remote login en
    Figure 2. Configure external login URL in the AM native console
  3. When the 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 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 ForgeRock Login Widget might not be able to rehydrate the journey and continue as needed.

Copyright © 2010-2024 ForgeRock, all rights reserved.