Passkey Login

Goal

Explain how to prepare and use Passkey login for sites in a remote browser environment.

Prerequisites

• The target site supports Passkey, WebAuthn, or security key login.
• The user has registered a Passkey on the target site.
• The remote browser access flow supports the required authentication interaction.

Steps

1. Confirm that the site URL, domain, and login flow are correct in site configuration.
2. The user opens the target site from the portal.
3. Select Passkey login on the target site.
4. Complete authentication according to browser prompts.
5. After successful login, confirm the remote browser enters the target business page.

Local Testing for Target Site Passkey

Passkey is strongly bound to the domain seen by the browser. When testing Passkey login for a target site, do not access it only through a server IP or a temporary forwarding address. The local browser must initiate HTTPS access with the target site domain, and the system must recognize that domain as a business domain that can be proxied.

Prepare as follows:

1. In the admin platform, go to "System Settings > Domain Management", click "Add Domain", and add the target site domain, for example login.example.com. This page corresponds to the admin-side Domains.vue page and is used to maintain business domains that the system is allowed to process.
2. Install the Caddy root certificate on the local computer. When an intranet or test environment uses Caddy internal certificates, the browser must trust this root certificate; otherwise Passkey/WebAuthn cannot complete authentication because HTTPS is not trusted. See Internal Certificate Installation.
3. Add the target site domain to local hosts and point it to the deployment server IP. For example:

<SERVER_IP> login.example.com

On Windows, usually edit C:\Windows\System32\drivers\etc\hosts; on macOS/Linux, usually edit /etc/hosts. After editing, reopen the browser and clear the DNS cache if necessary.

4. Access the test address with the target site domain:

https://<target-site-domain>/?saas=<...>&_d=<target-site-address>

Where:

Parameter	Description
<target-site-domain>	The domain added in "Domain Management" and pointed to the deployment server IP in local hosts
saas	The SaaS access parameter generated by the system or required by the business scenario
_d	The target site address, usually the URL that needs to be opened

After these preparations, the origin in the browser address bar is the target site domain and the HTTPS certificate is trusted locally. This provides the baseline conditions for testing Passkey login on the target site.

Verification

• The target site recognizes Passkey login.
• The user completes authentication and enters the site.
• If authentication fails, use site prompts and remote browser logs for troubleshooting.

FAQ

• Passkey is still an alpha-stage feature, and login may fail on some sites.