Customer Passkeys and Sign-In

This guide documents the exact manual customer passkey workflow verified on April 10, 2026 against:

Customer portal: https://customer.test.emali2.damplabs.com
Identity host: https://auth.test.emali2.damplabs.com

Passkeys are optional in the current rollout. Password login and the existing Use Mobile App To Login path remain available.

Before You Start

Use a customer account that can already sign in with username and password.
Use a supported browser and device for passkeys.
Keep in mind that passkeys are environment-specific. A passkey registered on the test auth host does not automatically work on production.
If the portal shows an initial customer login card, the Continue With Password button is expected. It is the handoff into the Keycloak username, password, and passkey screen.

Enroll the First Passkey

Route: /login -> /app/security/2fa -> Keycloak passkey registration -> /app/security/2fa

Open the customer portal login page.
Select Continue With Password.
Sign in with the customer username and password.
Open the security page from the portal menu, or browse directly to /app/security/2fa.
Confirm the page shows Passkeys: No passkey enrolled.
Select Set Up Passkey.
If Keycloak asks for confirmation, enter the same username and password again.
When the browser or operating system passkey sheet appears, complete the registration using one of the supported methods:
Touch ID or another built-in biometric prompt on the same device
A synced passkey from an iPhone, Android device, or platform account
A hardware security key
Wait for the browser to return to /app/security/2fa.
Confirm the page now shows 1 passkey enrolled.

Expected result: the passkey is registered, the customer returns to the portal security page, and password login still works as fallback.

Add Another Passkey

Route: /app/security/2fa

Open the customer security page.
Confirm the page already shows at least one enrolled passkey.
Select Add Another Passkey.
Complete the Keycloak re-authentication prompt if it appears.
Complete the device or browser passkey registration prompt.
Return to the portal and confirm the passkey count increases.

Use this flow when the customer wants separate credentials for a laptop, a phone, and a hardware key.

Route: /login -> Keycloak sign-in -> /app

Open the customer portal while signed out.
Select Continue With Password.
On the Keycloak sign-in page, watch for one of these two behaviors:
The browser opens the passkey prompt automatically.
The page shows Sign in with Passkey, which the customer selects manually.
Approve the passkey request on the current device, or choose the browser option to use a passkey from another device.
Complete the biometric, PIN, security-key touch, or approval step required by that device.
Confirm the browser redirects back to /app.

Expected result: the customer lands on the dashboard without re-entering the password.

Use a Passkey From Another Device

Route: /login -> Keycloak sign-in -> cross-device passkey prompt -> /app

Start from the normal customer login page.
Select Continue With Password.
On the Keycloak sign-in page, use the automatic passkey prompt or select Sign in with Passkey.
If the enrolled passkey is on another device, choose the browser or platform option to use a phone, tablet, or another nearby device.
Scan the QR code or follow the platform prompt shown by the browser.
Approve the sign-in on the device that holds the enrolled passkey.
Return to the original browser and confirm the portal redirects to /app.

This is the supported path for customers who register a passkey on one device and later sign in from a different laptop or browser.

Manage or Remove Passkeys

Route: /app/security/2fa -> Keycloak account management

Open the customer security page.
Select Manage in Account Settings.
Review the security credentials in the Keycloak account-management area.
Remove stale passkeys or review which credentials are active.
Return to the portal and select Refresh if the security page is still open.

Use this path when a device has been replaced, lost, or handed back to IT.

What Users Should Expect

The initial Continue With Password screen is part of the current customer web login experience.
Password login stays available even after passkey enrollment.
Use Mobile App To Login remains available and is not replaced by passkeys.
The customer security page is the main portal view for passkey status, trusted devices, and transaction-PIN status.
Manage in Account Settings opens centralized Keycloak account management rather than a local customer-only settings dialog.

Troubleshooting

The customer does not see a passkey prompt

Select Continue With Password first. The passkey controls live on the Keycloak sign-in screen, not the first customer landing card.
If the browser does not show a prompt automatically, look for Sign in with Passkey.
If neither appears, refresh the page and confirm the browser supports passkeys.

The portal still says `No passkey enrolled`

Refresh /app/security/2fa.
If the customer completed registration in Keycloak but the portal is stale, use the page Refresh action or sign out and sign back in.

The customer changed devices

Use Sign in with Passkey and choose the cross-device option if the passkey lives on another phone or laptop.
If the old device is gone and the passkey cannot be used, fall back to password login, then remove the old passkey from Manage in Account Settings and enroll a new one.

The passkey worked in test but not production

This is expected. Passkeys are tied to the Keycloak auth hostname for that environment.
A passkey registered on auth.test.emali2.damplabs.com must be enrolled again on the production auth hostname.