Advanced Identity Cloud/PingAM Login Widget

Registering a passkey

The Advanced Identity Cloud/PingAM Login Widget provides UI elements for the WebAuthn Registration node node, letting a signed-in user register a new passkey backed by their device, browser, or a hardware security key.

No additional widget configuration is required. The Advanced Identity Cloud/PingAM Login Widget detects a registration step from its callback shape and renders the appropriate UI automatically.

How it works

When the Advanced Identity Cloud/PingAM Login Widget encounters a WebAuthn registration step, it takes the following actions:

  1. Prompts the user to optionally name the new device, for example My Work Laptop.

  2. Calls the browser’s navigator.credentials.create() API to create a new passkey, using the challenge and relying party details from the server.

  3. Submits the resulting credential to the server to complete registration.

Browser prompt to create a new passkey
Figure 1. Creating a passkey

The exact prompt the user sees depends on their browser, operating system, and available authenticators. For example, the browser might show a platform biometric prompt, such as Touch ID or Windows Hello, for a device-bound passkey, or a picker for a hardware security key.

If the user cancels the browser prompt, or the browser reports another WebAuthn error, the Advanced Identity Cloud/PingAM Login Widget does not display its own error message.

It still submits the step to the server with the error recorded, so the WebAuthn Registration node node’s Client Error outcome fires as expected. Route that outcome to a message or fallback in your journey.

Configure your authentication journey

Because registering a passkey requires an authenticated session, add the WebAuthn Registration node node after a successful sign-in step in your journey, rather than as part of the sign-in journey itself.

Use the same configuration values in the WebAuthn Registration node node as you use in any WebAuthn Authentication node nodes in your sign-in journeys.

Configuration mismatches between these nodes cause authentication to fail.

In the WebAuthn Registration node node:

  1. In Origin domains, enter the URL where you host your app, for example https://app.example.com.

    If you leave Origin domains empty, the server uses the origin of incoming requests as an accepted origin.

  2. In Accepted signing algorithms, include one or more of ES256 and RS256.

  3. Ensure Limit registrations is not enabled, so returning users can register more than one passkey.

  4. Optionally, use Authentication attachment to control which type of authenticator the browser offers:

    Value Description

    PLATFORM

    Only allow authenticators built into the user’s device, such as Face ID, Touch ID, or Windows Hello.

    CROSS_PLATFORM

    Only allow external authenticators, such as hardware security keys.

    UNSPECIFIED

    Allow either type. This is the default.

  5. Optionally, to support usernameless sign-in later, enable Username to device.

Test the registration flow

Sign in to your app, then start a journey that includes the WebAuthn Registration node node.

The Advanced Identity Cloud/PingAM Login Widget prompts for an optional device name, then invokes the browser’s passkey creation flow. Complete the browser’s prompt to finish registration.

After a device is registered, configure passkey autofill to let the user sign in with it, or add a WebAuthn Authentication node node without conditional mediation to require an explicit passkey sign-in step.

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.
Implementing passkey autofill

Let users sign in with a registered passkey from the browser’s autofill picker.