Advanced Identity Cloud/PingAM Login Widget

Multi-factor authentication with OATH and Push

The Advanced Identity Cloud/PingAM Login Widget provides UI elements for registering a new OATH or Push device by scanning a QR code with the ForgeRock Authenticator app, and for verifying a one-time password from an already-registered device.

This page covers:

Registering a device with a QR code

Use the Combined MFA Registration node or Push Registration node node to let a user register a new device by scanning a QR code with the ForgeRock Authenticator app, instead of typing in a shared secret manually.

When the Advanced Identity Cloud/PingAM Login Widget encounters a step containing QR code data, it automatically:

  1. Renders a QR code image the user can scan with their authenticator app.

  2. Provides a fallback link and copyable URL for users who cannot scan the code, for example if testing on the same device that renders the widget.

  3. If the step also includes a polling callback, polls the server until the user completes registration on their device, then continues the journey automatically.

No additional widget configuration is required. This behavior is automatic whenever the journey step matches this shape.

Configure your authentication journey

Add the Combined MFA Registration node or Push Registration node node to a registration journey.

Connect the node’s outcomes to handle both successful registration and any failure paths your journey requires.

The Combined MFA Registration node node lets users choose between Push and OATH registration in a single step. Use the Push Registration node node if you only want to offer Push registration.

Test the registration flow

With your journey configured, start it in an app using the Advanced Identity Cloud/PingAM Login Widget. When you reach the registration step, the widget displays:

  • A QR code image

  • A collapsible section with a direct link to open the registration URL in the ForgeRock Authenticator app, and a copyable URL, useful when testing in a browser on the same device as the authenticator app

  • A loading indicator while the widget polls the server for registration completion

Scan the QR code with the ForgeRock Authenticator app (or open the fallback link on a mobile device) to complete registration. The journey continues automatically once the server detects the new device.

Verifying a one-time password

The Advanced Identity Cloud/PingAM Login Widget provides UI elements for the OATH Token Verifier node but not currently the standalone OATH Registration node. Use the QR code registration flow above instead.

Once a user has registered the ForgeRock Authenticator for one-time passwords, for example using the flow above, the Advanced Identity Cloud/PingAM Login Widget can accept a one-time password from the authenticator app.

The Advanced Identity Cloud/PingAM Login Widget requires that the OATH Token Verifier node is contained within a Page node configured with a specific Stage property.

In the containing Page Node, set the Stage property to OneTimePassword:

law oath journey with stage en
Figure 1. OATH journey example

The Advanced Identity Cloud/PingAM Login Widget detects that stage value as a special case and renders the appropriate UI:

law oath ui with stage en
Figure 2. Rendering with the OneTimePassword stage property

If you do not put the OATH Token Verifier node within a Page node, the Advanced Identity Cloud/PingAM Login Widget will not render the UI correctly:

law oath ui en
Figure 3. Rendering a lone OATH Token Verifier node

Displaying recovery codes

Use the Recovery Code Display node node after a device registration step to give users backup codes they can use to authenticate if they lose access to their registered device.

When the Advanced Identity Cloud/PingAM Login Widget encounters this node’s callback, it automatically renders the device name and a formatted grid of recovery codes for the user to save or print.

Configure your authentication journey

Add the Recovery Code Display node node to your registration journey, after the node that registers the device.

To let users authenticate with a previously issued recovery code, add the Recovery Code Collector Decision node node to your login journey.

Test the flow

Complete a device registration journey that includes the Recovery Code Display node node. After registration succeeds, the Advanced Identity Cloud/PingAM Login Widget displays:

  • A header confirming that MFA is now enabled

  • The name of the registered device

  • A list of one-time-use recovery codes

The server returns recovery codes only once, immediately after registration.

Advise your users to save or print them before continuing, as the Advanced Identity Cloud/PingAM Login Widget does not provide a way to view previously issued codes again.
Passkeys

Passwordless sign-in and registration with passkeys.