Handling Passkeys in ACCELQ – ACCELQ

What is a passkey?

Passkeys are a passwordless authentication mechanism based on the FIDO2 and WebAuthn standards. Instead of authenticating a user with a shared secret such as a password, passkeys use public-key cryptography.

When a passkey is registered with an application, a cryptographic key pair is created:

The public key is registered with the application or identity provider.
The private key remains associated with the authenticator and is used to sign authentication challenges.
During login, the application sends a challenge that must be cryptographically signed using the corresponding private key.

Because the private key is not transmitted to the application during authentication, passkeys provide stronger protection against credential theft, phishing, and password reuse.

From an automation perspective, passkey-based authentication introduces an additional challenge. The passkey credential and its associated authenticator must be available within the browser session where the automated authentication flow is executed.

ACCELQ Passkey Helper

ACCELQ Passkey Helper captures passkeys so they can be used in ACCELQ automation. A captured passkey can be saved to the ACCELQ Agent on the current machine or prepared for transfer to another machine.

Set up and start ACCELQ Passkey Helper

Download and extract the setup

Download the ACCELQ Passkey Helper setup ZIP on the machine where the ACCELQ Agent is installed. Contact ACCELQ Support for the setup link.
Extract the ZIP file.
Open a command prompt or terminal in the extracted setup directory.

Start the app in browser mode

Start the app in browser mode. The browser mode opens a controlled Chrome browser and displays the ACCELQ Passkey Helper panel in the bottom-right corner of the monitor.

Run the command for your operating system.

macOS or Linux with a desktop interface

./run.sh browser

Windows

run.bat browser

In these commands, browser is the CLI mode argument. The setup automatically detects the ACCELQ Agent installation.

Application controls

The toggle in the top-right corner of the ACCELQ Passkey Helper panel is disabled by default. Enabling the toggle routes the browser's passkey requests to the ACCELQ Passkey Helper.

Modes

The helper supports two browser-session modes:

Capture mode: Creates and captures a new passkey when the application is ready to register one.
Verify identity mode: Uses an existing saved passkey when the application requires identity verification.

The helper also provides two save options:

Add to Agent: Saves the newly captured passkey directly to the ACCELQ Agent on the current machine.
Save for Export / Import: Saves the newly captured passkey in ACCELQ Passkey Helper so it can be exported and imported into another machine.

Understanding Passkey Helper Modes

Capture mode

Use Capture mode when the application is ready to create and register a new passkey.

Start ACCELQ Passkey Helper in browser mode.
In the controlled Chrome browser, navigate to the page where the application allows a new passkey to be created.
Turn on the ACCELQ Passkey Helper toggle.
Select Capture mode.
Create the passkey in the application.
Confirm that the application reports that the passkey was created successfully.
Select the appropriate save option.

Add to Agent: Saves the captured passkey to the ACCELQ Agent on the current machine so it can be used for ACCELQ automation on that machine.
Save for Export / Import: Saves the captured passkey in the Helper's saved folder without adding it to the ACCELQ Agent on the current machine. Use this option when the passkey must be transferred to another machine.

After confirming that the passkey was saved, select Close browser.

Verify identity mode

Use Verify identity mode when the ACCELQ Agent on the current machine already contains a passkey for the application and the application asks to authenticate the username used to login in the controlled browser using the saved passkey in the ACCELQ agent.

Start ACCELQ Passkey Helper in browser mode.
In the controlled Chrome browser, navigate to the application login page.
Turn on the ACCELQ Passkey Helper toggle.
Select Verify identity mode.
Start the application's passkey login or identity-verification process. ACCELQ Passkey Helper automatically supplies the matching passkey stored in the ACCELQ Agent.
After authentication succeeds, navigate to the profile or security settings where another passkey can be created.
Before creating the new passkey, switch ACCELQ Passkey Helper from Verify identity mode to Capture mode.
Create the new passkey and confirm that the application reports that it was created successfully.
Select Save for Export / Import. The new passkey is saved in the Helper's saved folder and is not added to the ACCELQ Agent on the current machine.
Select Close browser.

ACCELQ Passkey Helper CLI modes

The word after run.sh or run.bat is the CLI mode argument. Use the lower-case mode names shown below.

If no mode is provided, ACCELQ Passkey Helper defaults to probe, which is a safe, read-only mode. The Helper prints the selected mode before performing any action.

macOS or Linux

./run.sh [mode]

Windows

run.bat [mode]

Mode	What it does	When to use it
`probe`	Lists passkeys stored in the ACCELQ Agent without making changes.	Inspect the passkeys currently available to the Agent.
`browser`	Opens a controlled Chrome browser and displays ACCELQ Passkey Helper.	Capture a new passkey. Verify identity with an existing passkey. Add a newly captured passkey directly to the local ACCELQ Agent. Save a newly captured passkey for a later export or import.
`export-saved`	export-saved CLI mode exports passkeys from the ACCELQ Passkey Helper’s `saved` folder instead of reading from the ACCELQ Agent. The export is written under the `auth_cache` directory	Run after selecting Save for Export / Import in `browser` mode.
`import-saved`	Merges passkeys from the ACCELQ Passkey Helper’s `saved` folder into the ACCELQ Agent on the same machine. This mode: Always merges the saved passkeys with the Agent's existing passkeys. Replaces an older passkey only when the incoming passkey represents the same application and login. Deletes the `saved` folder after the passkeys have been merged successfully.	Add staged passkeys to the Agent without creating a cross-machine export.
`probe-saved`	Lists passkeys in the ACCELQ Passkey Helper’s `saved` folder without making changes.	Inspect staged passkeys before exporting or importing them.
`export`	export arg reads the passkeys stored in the ACCELQ Agent and creates a dated export under: `auth_cache/<timestamp>/web_auth/webauthn_export.bin` The export contains the credential data and the information required to import it on another machine. Security notice: Treat the complete export folder as sensitive authentication material. Store and transfer it only through an approved secure channel. After a successful export, the source passkeys are removed from the ACCELQ Agent.	Use primarily when migrating the passkeys from an existing Agent machine.
`import`	Import selects the latest export, prepares it for the current machine, and loads it into the ACCELQ Agent. After a successful import, the consumed export is moved under: `auth_cache/.imported/` This prevents the same export from being imported again accidentally. The imported passkeys are merged with those already available in the Agent.	Restore or transfer exported passkeys to the target Agent.

Important:

export-saved removes successfully exported passkeys from the Helper's saved folder.

export removes successfully exported passkeys from the ACCELQ Agent.

Command examples

The examples below use macOS or Linux. On Windows, replace ./run.sh with run.bat.

./run.sh
./run.sh probe
./run.sh browser
./run.sh export-saved
./run.sh import-saved
./run.sh probe-saved
./run.sh export
./run.sh import

Running ./run.sh without a mode is the same as running ./run.sh probe. Running run.bat without an argument, including by double-clicking it on Windows, also defaults to probe.

Transfer the passkey to another machine

On the current machine, export the saved passkey.

macOS or Linux
```
./run.sh export-saved
```
Windows
```
run.bat export-saved
```
Confirm that the exported cache is available in the auth_cache folder.
Download and extract ACCELQ Passkey Helper on the target machine where the other ACCELQ Agent is installed.
Copy the complete auth_cache folder to the ACCELQ Passkey Helper setup directory on the target machine.
Import the passkey into the ACCELQ Agent on the target machine.

macOS or Linux

./run.sh import

Windows

run.bat import

The passkey is now available to the ACCELQ Agent on the target machine for ACCELQ automation.

Passkey merge rules

The same merge rules apply to:

import
The Add to Agent and Save for Export / Import actions in browser mode.
import-saved

Existing passkeys are not removed during a merge unless an incoming passkey replaces an older passkey for the same application and login.

Situation	Result
The incoming passkey is identical to an existing passkey, or only the sign count (usage count) differs	The copy with the higher sign count (usage count) is retained
The application and login are the same, but the underlying passkey is different	The incoming passkey replaces the existing passkey
The passkey does not match an existing application and login	The incoming passkey is added alongside the existing passkeys

In this context, incoming means the passkey being imported or the passkey newly captured through browser mode.

Enable passkey authentication during ACCELQ automation

After saving the application’s passkey in the ACCELQ Agent, to use a passkey stored in the ACCELQ Agent during an automated run:

Configure the Login Action

Use Invoke Browser to open the application URL.
Immediately after it, add Enable Virtual Authentication on Web Browser.
Include the Login Action in the Scenario setup for each applicable test case.

Command behavior

The Enable Virtual Authentication on Web Browser command:

Enables virtual authentication for all browsers that are already open and any browser opened later in the same test case.
Automatically restores passkeys and security-key sign-ins stored in the ACCELQ Agent, allowing registered sign-ins to be reused across runs.

Here is an article that explains how to work with passkeys for Salesforce using the ACCELQ Passkey Helper:

Handling Salesforce Passkeys with ACCELQ Passkey Helper

A similar approach can be used for other applications that support passkey-based authentication.