Passkey Authentication

ProAuth supports passkey-based passwordless authentication for UserStore identity providers using the WebAuthn standard (FIDO2). Users can sign in with a hardware security key, platform authenticator (Windows Hello, Touch ID, Face ID), or a synced passkey from a password manager — without entering a password.

Enabling Passkeys

To enable passkey support for a UserStore IDP instance, configure the following options:

Option	Type	Default	Description
PasskeyEnabled	bool	false	Enables passkey registration and authentication
PasskeyRpName	string	ProAuth	Relying Party display name shown by clients that expose it
PasskeyAllowedOrigins	string	(empty)	Optional comma-separated list of additional allowed origins. The primary origin is derived from BaseServiceSettings:HostUrl
PasskeyConditionalUiEnabled	bool	true	Enables WebAuthn Conditional UI (autofill passkey suggestions in the username field)
PasskeyAllowLoginWithoutUserVerification	bool	false	Allows passkeys without User Verification for login (not recommended)
PasskeyEnforcePasswordless	bool	false	Forces all users with passkeys to use passkey login (disables password login)
PasskeyAuthenticatorTimeoutSeconds	int	180	Timeout for the WebAuthn ceremony in seconds
PasskeyAttestationConveyance	string	none	Attestation preference: none, indirect, direct, or enterprise
AccountManagementLinkVisibility	string	auto	Controls the Account Management link on the login page: auto shows it when passkeys are enabled, enabled always shows it, and disabled hides it

WARNING

BaseServiceSettings:HostUrl must be set correctly. ProAuth derives the WebAuthn RP ID from this URL's hostname. For example, if users access ProAuth at https://login.example.com, the RP ID is login.example.com. Passkey registrations are bound to this domain and cannot be used on a different domain.

Passkey Server Domain Considerations

The RP ID (Relying Party Identifier) is a critical WebAuthn concept:

• It must be a valid domain that is equal to or a registrable domain suffix of the origin
• For example, if the login page is at https://auth.company.com, valid RP IDs are auth.company.com or company.com
• Using a broader domain (e.g., company.com) allows passkeys to work across subdomains
• Changing the RP ID after users have registered passkeys will invalidate all existing passkey registrations

DANGER

Never change the hostname of BaseServiceSettings:HostUrl after users have registered passkeys. Doing so will prevent all existing passkeys from authenticating.

Passwordless Login Flow

When passkeys are enabled, the login page shows additional options:

1. Conditional UI (if enabled): The browser's password autofill menu includes available passkeys. Users can select a passkey directly from the username field.
2. Explicit button: A "Sign in with passkey" button triggers the WebAuthn ceremony explicitly.

Enforcing Passwordless Login

There are two levels of enforcement:

1. IDP-level (PasskeyEnforcePasswordless = true): All users with at least one registered passkey are required to use passkey authentication. Password login is rejected with an error message.

2. User-level (via Account Management portal): Individual users can opt in to require passkey login for their account by enabling the "Require passkey for login" setting.

INFO

Both enforcement levels only apply when the user has at least one passkey registered. Users without passkeys can always log in with a password.

Managing Passkeys

Users manage their login passkeys through the Account Management portal at /account/security. The portal uses a dedicated OIDC authentication flow and provides a self-service interface for registering, renaming, and removing passkeys.

By default, the UserStore login page shows the Account Management link only when passkeys are enabled. Set AccountManagementLinkVisibility to enabled to always show the link, or disabled to hide it.

Security Considerations

• Phishing resistance: Passkeys are bound to the RP ID origin, preventing phishing attacks
• User Verification: For login, userVerification: "required" ensures the authenticator verifies the user's identity (PIN, biometric, etc.)
• Attestation: The default none is recommended for most deployments. Use direct or enterprise only if you need to verify the authenticator's make and model
• Backup eligibility: Synced passkeys (e.g., iCloud Keychain, Google Password Manager) are marked as backup-eligible. Platform-bound keys (e.g., hardware security keys) are not