Passkeys

Passkeys let Forkiva web users sign in with their device screen lock instead of entering their password. Depending on the device, this can be Touch ID, Face ID, Windows Hello, a PIN, or a physical security key.

Passkeys are an additional sign-in method. They do not remove or replace a user's password, and the password remains the recovery method if a device is lost.

Who does what

Person	Responsibility
System administrator / DevOps	Deploy the feature, run migrations, configure the relying-party domain, HTTPS origins, and persistent cache storage.
Forkiva administrator	Ensures users have active accounts and can help with normal password-reset recovery when needed.
End user	Signs in with their password once, creates a passkey in their profile, and manages their own passkeys.

An administrator cannot create a user's passkey on their behalf. Creating a passkey requires the signed-in user to approve the request on their own device.

What is supported

• Passkey enrollment and passwordless sign-in are available in the Forkiva Vue web application.
• Any active Forkiva user can add one or more passkeys to their own account.
• Inactive or deleted users cannot sign in with a passkey.
• Forkiva Driver and Employee mobile apps continue to use their existing authentication flows.
• A modern browser and a secure connection are required. Browsers treat localhost as a development exception; a deployed site must use HTTPS.

Administrator setup

1. Install the release and run migrations

Install the Forkiva release that includes passkey support, then run the normal module migrations from the forkiva/ application directory:

php artisan module:migrate -a

The migration creates the passkeys table in the User module. Forkiva also requires the Core module's cache and cache_locks tables when database cache storage is used.

2. Configure persistent ceremony storage

Passkey registration and sign-in are two browser requests: Forkiva first issues a short-lived challenge, then verifies the signed credential. The challenge must be stored in persistent storage shared by both requests.

Do not use Laravel's array or null cache drivers for passkeys. They disappear at the end of a request and cause an immediate “The passkey request expired” message.

For a single-server installation using the database cache driver, configure the application .env:

CACHE_STORE=database
PASSKEYS_CACHE_STORE=database

For a multi-server installation, configure PASSKEYS_CACHE_STORE to a shared cache store such as Redis. All application servers must use the same passkey cache storage and prefix.

3. Configure the web origin

Set these values in the application .env before any user enrolls a passkey:

PASSKEYS_RELYING_PARTY_ID=app.example.com
PASSKEYS_ALLOWED_ORIGINS=https://app.example.com
PASSKEYS_ENABLED=true
PASSKEYS_CACHE_STORE=database
PASSKEYS_TIMEOUT=60000

Setting	Meaning
PASSKEYS_ENABLED	Deployment default for whether passkey endpoints are available. It can be overridden by an administrator in Forkiva Settings.
PASSKEYS_RELYING_PARTY_ID	The host name only of the web app. Do not include https://, a port, or a path.
PASSKEYS_ALLOWED_ORIGINS	Exact browser origins allowed to perform passkey ceremonies. Include the scheme, and separate multiple origins with commas.
PASSKEYS_CACHE_STORE	Persistent Laravel cache store for one-time passkey challenges. Use database or a shared store such as Redis.
PASSKEYS_TIMEOUT	Browser prompt lifetime in milliseconds. The default is 60000 (one minute).
PASSKEYS_USER_HANDLE_SECRET	An optional stable deployment secret used to derive non-personal WebAuthn user handles. Set it once in production and keep it unchanged.

The relying-party ID belongs to the Forkiva page opened in the browser, not an API path. For example, an application loaded at https://app.example.com uses app.example.com as its relying-party ID.

For local development with Forkiva opened through Laravel at http://localhost:8000, use:

PASSKEYS_RELYING_PARTY_ID=localhost
PASSKEYS_ALLOWED_ORIGINS=http://localhost:8000
PASSKEYS_CACHE_STORE=file

Use one host name consistently. localhost, 127.0.0.1, and forkiva.test are different WebAuthn identities and cannot be mixed.

4. Clear cached configuration and verify

After changing environment values, clear cached Laravel configuration:

php artisan config:clear

Then sign in with a normal password, open the user profile menu, select Passkeys, and create a test passkey. Confirm that it appears in the list and can be used from the sign-in page.

5. Manage passkeys from Forkiva Settings

An administrator with the Edit settings permission can open Settings → Passkeys to:

• Enable or disable passkey registration and sign-in globally.
• Set the relying-party ID to the exact Forkiva host.
• Add the exact allowed Forkiva browser origins.
• Change the browser request timeout.

These database-backed settings override the corresponding .env defaults at runtime. Disabling passkeys hides the sign-in and profile actions and makes all passkey API endpoints unavailable. Existing enrolled passkeys are retained and work again after the feature is re-enabled.

Cache storage and PASSKEYS_USER_HANDLE_SECRET remain deployment-only settings because changing them through the application UI could interrupt active requests or make existing credential identities unstable.

End-user guide

Add a passkey

1. Sign in to Forkiva with your username/email and password.
2. Open the profile menu in the top-right corner.
3. Select Passkeys.
4. Enter a clear name for the device, such as Work MacBook or Office security key.
5. Select Add Passkey.
6. Follow the browser or device prompt. Confirm with your fingerprint, face, device PIN, or security key.
7. Wait for the success message. The passkey then appears in the list.

Use a name that helps you recognize the device later. You can add more than one passkey, which is recommended for a second trusted device or security key.

Sign in with a passkey

1. Open the Forkiva sign-in page.
2. Select Sign in with a passkey.
3. Choose the available device or password manager.
4. Approve the request with your device screen lock or security key.
5. Forkiva signs you in to the same account without asking for its password.

Use a phone by scanning the QR code

Some desktop browsers offer Use a phone or tablet and show a QR code. This is a FIDO cross-device request, not a normal website QR code.

1. Keep the QR code open on the computer.
2. Turn on Bluetooth on the computer and phone, keep them nearby, and ensure both have an internet connection.
3. Scan the code with the phone's built-in Camera or system QR scanner.
4. Choose Use passkey when Android or iOS prompts you.
5. Confirm with the phone's screen lock.

Do not copy, search, or share the FIDO:/... text returned by a generic QR scanner. It is a short-lived handoff payload, not a URL. If the phone only displays that text instead of asking to use a passkey, use the browser's local device option instead, or update the phone, browser, and password manager. Android passkeys require Android 9 or newer and a screen lock. See Google's passkey guidance for device-specific steps.

Remove a passkey

1. Sign in using another passkey or your password.
2. Open Profile → Passkeys.
3. Select the trash icon beside the device you want to remove.
4. Confirm the removal.

Remove a passkey promptly when you lose a device, replace a security key, or no longer trust a device. Keep at least one other recovery method—another passkey or your password—before removing the current device's only passkey.

Security and operations

• Forkiva stores a public credential record, not a user's fingerprint, face data, device PIN, or private passkey key.
• Each registration and sign-in challenge is short-lived and can be used only once.
• Passkey login options and verification attempts are rate limited.
• Do not change the relying-party ID, allowed origins, or user-handle secret casually after users have enrolled. A domain change can require users to enroll new passkeys.
• Include the passkeys table in normal database backups. cache and cache_locks hold temporary ceremony and lock data, so they do not need to be restored from a backup.
• Keep password login available. It is the recovery path for lost, unavailable, or unsupported passkey devices.

Troubleshooting

Message or symptom	Cause	Resolution
The RP ID "..." is invalid for this domain	The relying-party ID does not match the hostname of the page in the browser.	Set PASSKEYS_RELYING_PARTY_ID to the Forkiva host only and set the exact origin in PASSKEYS_ALLOWED_ORIGINS. Clear config cache.
The passkey request expired. Please try again. immediately after approval	The challenge was stored in a non-persistent cache driver, or the QR/prompt is stale.	Use PASSKEYS_CACHE_STORE=database or Redis; do not use array or null. Create a new passkey request.
QR scan shows FIDO:/... as plain text	A generic QR reader decoded the payload but did not launch the device passkey flow.	Use the phone Camera/system scanner, enable Bluetooth, or create the passkey on the desktop device instead.
The passkey credential is invalid	The passkey was removed, belongs to another site, the request was cancelled, or configuration changed after enrollment.	Start a new request. If it persists, sign in with the password, remove the affected passkey, verify the domain configuration, and enroll it again.
No passkey option appears	Passkeys are disabled in Forkiva Settings, the browser/device does not support WebAuthn, or the page is not in a secure context.	Check Settings → Passkeys, then use a current supported browser and HTTPS in production. For local testing, use localhost consistently.
User cannot sign in after a device is lost	The user has no available passkey on another device.	Use normal password sign-in or the existing password-reset process, then remove the lost-device passkey and enroll a replacement.

Support checklist

When escalating a passkey issue, provide the browser name/version, device and operating-system version, the Forkiva URL (without credentials), whether the failure is enrollment or sign-in, and the exact visible error. Do not send screenshots of active QR codes or share passkey prompts; they are short-lived authentication handoff data.