Rapls Passkey Manual (Pro Edition)

Version 0.14.93 | PHP 8.2 or later | WordPress 6.0 or later | Requires Rapls Passkey (free) 0.12.0 or later, installed and active
The Pro edition builds on the full feature set of the free Rapls Passkey plugin, adding cross-device QR login, role-based passkey enforcement, recovery codes, email magic links, passwordless sign-up, adaptive step-up authentication, trusted device management, authenticator policy (FIDO MDS / AAGUID), security webhooks, adoption reports, multisite support, and more. For the free features and basic configuration, see the Free Manual.

Getting Started

License Activation

Rapls Passkey Pro is a one-time-purchase, license-based add-on distributed outside WordPress.org. When you purchase, a license key is issued immediately to the email address you registered. License keys take the form RPPK-XXXX-XXXX-XXXX-XXXX (four groups of four characters).

Steps from installation to license activation:

1. Install and activate the free Rapls Passkey plugin (0.12.0 or later).
2. Purchase from the Rapls Passkey Pro sales page and download rapls-passkey-pro.zip from the email you receive.
3. In the WordPress admin, go to Plugins > Add New > Upload Plugin, upload the ZIP, and activate Rapls Passkey Pro.
4. Open Settings > Rapls Passkey Pro > License.
5. Paste RPPK-XXXX-XXXX-XXXX-XXXX into the License Key field and enter the email address you used at purchase (the key is bound to that email).
6. Click “Activate.” When the status changes to Active, you’re done.

Requirements

Quick Start (Recommended Order)

1. Activate the license — enter your key and email under Settings > Rapls Passkey Pro > License.
2. Encourage enrolment — enable the enrolment prompt to nudge users to register a passkey.
3. Prepare recovery methods — enable recovery codes and email login (magic link) first, so there’s a path when a passkey isn’t available.
4. Enforce gradually — choose target roles and set a grace period to require passkeys (start with a subset of roles).
5. Step-up — require passkey confirmation after a password login (start with adaptive).
6. Enforce passwordless — once adoption settles, consider disabling password login, blocking application passwords, and refusing password resets.
7. Set up operations — configure authenticator policy, webhooks, and adoption reports.

Cross-Device QR Login

This is a distinctive cross-device login where the computer displays a QR code, you scan it with your phone, and you approve with a passkey. Even if the computer has no passkey registered, you can sign in with the passkey on the phone in your hand. It works even when the devices are far apart.

How QR Login Works

1. On the login screen, choose “Approve on another device,” and the computer displays a QR code and a 4-digit confirmation code.
2. Scan the QR code with your phone’s camera, and the approval screen opens.
3. Enter the 4-digit confirmation code shown on the computer into your phone.
4. Approve with the phone’s passkey (Touch ID / Face ID / screen lock, etc.), and the login on the computer completes.

The 4-Digit Confirmation Code (Relay / Phishing Protection)

The 4-digit code shown on the computer must be entered before you approve on the phone. This mechanism prevents attacks where an attacker relays their own login for a victim to approve.

• A phishing victim sent only a link cannot see the attacker’s computer screen, so they cannot enter the code.
• If you mistype the code, you can correct it without repeating the passkey prompt.
• Repeated wrong entries invalidate the request.

Filters and the Same-Network Constraint

Passkey Enforcement

Configure this under “Passkey Enforcement” in Settings > Rapls Passkey Pro. You can require users in chosen roles to register a passkey and migrate them in phases via a grace period.

Enforcement by Role

Grace Period & Phased Rollout

When enforcement is enabled, users in target roles see a prompt encouraging passkey enrolment during the grace period. When the grace period ends, they are required to register a passkey after login. You can migrate existing users by deadline rather than burdening everyone at once.

Lockout Prevention

The following safety valves are always in effect so that nobody is shut out.

• The last administrator — the last administrator remaining on the site is exempt from enforcement.
• Emergency bypass — defining define('RAPLS_PASSKEY_BYPASS', true); in wp-config.php temporarily lifts enforcement (break-glass).
• Recovery codes — when a passkey isn’t available, users can recover with a recovery code.
• Users who haven’t registered a passkey yet — users without a passkey are not locked out and are guided to enrol.

Recovery & Alternative Logins

These are alternative logins and recovery methods for when a passkey isn’t available. None of them are passkeys themselves, so they aren’t as strong as a passkey sign-in. Enable them carefully, for recovery purposes.

Recovery Codes

Issues single-use recovery codes. They are a break-glass method for when a passkey isn’t available, and can also be used from the “Can’t use your passkey?” link on the login screen.

Email Login (Magic Link)

Sends a one-time login link by email (disabled by default). It’s a fallback / recovery method for when a passkey isn’t available.

Passwordless Sign-Up (Passkey Sign-Up)

Lets users create a new account with a passkey from the login screen. The account is created only after the passkey verification succeeds (bot protection).

Enforcing Passwordless

Adaptive Step-Up Authentication

After a password login, requires passkey confirmation once more. There are two modes: “adaptive,” which asks based on risk, and “two-factor,” which asks every time.

The mode can also be set via the rapls_passkey_stepup_mode filter.

Disabling Password Login

For users in enforced roles who already have a passkey, refuses interactive password login (fully passwordless).

Blocking Application Passwords / Refusing Password Reset

Closes the “back doors” that users meant to be passwordless still hold. Configure these under “Disabling Password Login” in Settings > Rapls Passkey Pro. Both are disabled by default and require “Disabling Password Login.”

Device & Enrolment Management

Trusted Device Management

On the profile screen you can review and revoke the list of devices for which step-up no longer requires passkey confirmation. Once a device has confirmed, step-up stops asking it for a passkey (that’s the point), but it also means a device you’ve parted with (sold, lent, or used just once) silently retains the exemption.

Login Session Management

Review active login sessions (time, IP, browser) on the profile screen and end them individually, all others, or all. There’s also an option to automatically end other sessions on a passkey login.

Enrolment Prompt

Shows a prompt after login encouraging users who don’t have a passkey yet to enrol. Even if dismissed, it reappears after a while.

Authenticator Policy

Under “Authenticator Policy” in Settings > Rapls Passkey Pro, restrict the types of authenticators that can be registered.

FIDO Metadata Service (MDS)

Periodically downloads the FIDO Alliance’s authenticator metadata, verifies the BLOB signature (chained to the GlobalSign root certificate), and caches it. As a registration policy, you can choose one of the following.

• Reject authenticators FIDO has flagged as problematic (revoked / compromised).
• Allow only FIDO-certified authenticators (a minimum level of L1 / L2 / L3 can be set).

The policy applies only to authenticators that report an AAGUID. You can configure whether to allow authenticators not present in the metadata (such as synced passkeys). The settings screen shows the fetch status and a “Refresh now” button.

AAGUID Allow / Deny Lists

Control the registration of specific authenticators with allow / deny lists of the AAGUID that identifies an authenticator model. This can be combined with the device-bound-only setting (reject synced passkeys).

Cross-Domain Support (Related Origin Requests)

Outputs /.well-known/webauthn so that passkeys with the same RP ID can be shared across multiple domains. Settings export / import round-trips the Related Origins list correctly too.

Notifications & Reports

Security Webhooks

Sends security events such as passkey registration, deletion, and sign-in to Slack / Microsoft Teams / generic JSON (for SOC / SIEM integration, non-blocking).

Adoption Reports (Periodic Digest)

Emails administrators a summary of passkey adoption (enrolment rate by role and recent activity), weekly or monthly (disabled by default).

Reminders for Unenrolled Users

Periodically emails active users who haven’t registered a passkey, encouraging them to enrol (disabled by default).

Adoption Analytics & Downgrade Detection

Shows enrolment rate by role and activity over the last 30 days as analytics. You can also set the audit-log retention period, and old records are deleted daily.

Operations & Automation

Multisite

Supports network-wide policy management and a shared RP ID. From the network admin, you can apply a common passkey policy to member sites.

Settings Export / Import

You can export / import the free and Pro settings as JSON. Use it to migrate from staging to production or to roll out to multiple sites at once.

WP-CLI

Commands for server-side automation and break-glass recovery.

# Fetch and verify FIDO metadata
wp rapls-passkey-pro mds-refresh

# Generate recovery codes (count optional)
wp rapls-passkey-pro recovery-generate --user=<user> [--count=<n>]

# Invalidate recovery codes
wp rapls-passkey-pro recovery-clear --user=<user>

# Show adoption status by role and activity over the last 30 days
wp rapls-passkey-pro report

Frequently Asked Questions

FAQ

Q: Can I install Pro without the free version?

A: No. Rapls Passkey Pro is an add-on to the free version. First install and activate the free Rapls Passkey (0.12.0 or later), then install Pro. If the free version is older than 0.12.0 or inactive, Pro refuses to boot and shows a notice in the admin.

Q: Can I use one license on multiple sites?

A: A 1-site license can be activated on 1 site; a 5-site license on 5 sites. For sites beyond the limit or when migrating a production site, “Deactivate” on the old site first, then “Activate” on the new one. The license is a one-time purchase with no expiry, and you can keep using it without renewing.

Q: If my license lapses (I don’t renew), do the Pro features stop?

A: No. Because it’s a one-time purchase, you can keep using the Pro features without renewing. One year of updates is included, and renewal from the second year onward is optional. Even if the license server is temporarily down, a license that was valid until just before continues to work through a 14-day grace period. Only revoked licenses are rejected.

Q: What is the 4-digit code in QR login for?

A: It’s relay / phishing protection. It prevents attacks where an attacker sends only a link to a login they’ve set up and gets the victim to approve it. Since the victim can’t see the attacker’s computer screen, they can’t enter the 4-digit code shown there, and the approval doesn’t go through. You can disable it with the rapls_passkey_pro/qr_confirmation_code filter, but normally leave it on.

Q: If I enforce passkeys, won’t users get locked out?

A: There are multiple safety valves so they don’t. The last administrator is exempt, define('RAPLS_PASSKEY_BYPASS', true); provides emergency relief, recovery codes and email login provide recovery, and users who don’t have a passkey yet are guided to enrol. We recommend enabling recovery methods before enforcement and trying a subset of roles first.

Q: What’s the difference between “Disabling Password Login” and “Blocking Application Passwords”?

A: “Disabling Password Login” refuses interactive password login (the login screen). Application passwords, on the other hand, are long-lived shared secrets that reach the REST API / XML-RPC without passing the interactive gate — a “back door” that remains even after disabling password login. To be fully passwordless, block both. Both use the same safety valves, so nobody is locked out.

Q: Do magic links or recovery codes bypass two-factor authentication (2FA)?

A: They don’t. If the site uses a 2FA plugin (Wordfence Login Security / Two-Factor, etc.) and the user has set up a second factor, magic-link and recovery-code logins stop at the two-factor challenge screen before an auth cookie is issued (requires free version 0.10.0 or later). A passkey sign-in (including the QR flow) is itself a second factor, so it isn’t challenged.

Q: When should I revoke a trusted device?

A: When you’ve sold or lent a device, or have one you used just once. Because step-up stops asking a once-confirmed device for a passkey, a device you’ve parted with keeps the exemption. From the trusted device list on the profile screen, revoke trust individually or for all devices (this also forgets the remembered sign-in locations).

Q: Does the authenticator policy (MDS / AAGUID) affect synced passkeys?

A: The MDS policy applies only to authenticators that report an AAGUID. You can configure whether to allow authenticators not present in the metadata, such as synced passkeys. Choosing “device-bound only” rejects synced passkeys. Making it too strict can prevent users from registering, so configure it with your target users’ authenticators in mind.

Q: Are webhook URLs stored securely?

A: Yes. Slack / Teams URLs are effectively bearer secrets, so they are encrypted at rest. Delivery uses a safe HTTP client that doesn’t go to internal / loopback addresses and follows no redirects, preventing SSRF. On settings export / import, they round-trip in plaintext so they can travel between sites.

Q: Do adoption reports or reminders contain personal information?

A: The adoption report contains only aggregate figures and no personally identifying information. Reminders for unenrolled users are sent to each user individually and include a one-click unsubscribe link. Enforced roles are excluded from reminders and receive enforcement guidance instead.