Passkey authentication

The eQual framework allows authentication using a passkey instead of a password, enhancing security and user convenience. This approach eliminates the risks associated with password theft, such as phishing attacks or brute force attempts, by relying on cryptographic keys rather than user-generated credentials. Passkeys can be securely stored on the user's device or hardware token and offer seamless integration with multi-factor authentication methods, ensuring a robust defense against unauthorized access.

Notes

• The passkey authentication is disabled by default, enable the setting core.security.passkey_creation to activate it.
• To test it in development mode, use localhost hostname instead of equal.local. Passkey authentication in a browser requires HTTPS protocol, but localhost is an exception that allows HTTP protocol.

Authentication workflows

1. If the user has no passkey yet

Steps

1. Enter login: The user provides their username or email.
2. Enter password: The user enters their password for initial authentication.
3. Prompt to register a passkey: After successful authentication, the system proposes passkey registration.
   • Options:
     • Register: The user proceeds to register a passkey. The system generates the required challenge, and the user’s device completes the registration process.
     • Ignore: The user skips registering a passkey for now. They can be reminded again later.
     • Ignore and do not ask for passkey registration again: The user opts out of passkey registration permanently, and the system respects this preference.

Register passkey technical diagram

The relying party is the eQual backend API, it proposes 2 endpoints for passkey registration:

• get=user_passkey-register-options
• do=user_passkey-register

Example:

A user logs into their banking app for the first time. After entering their password, they are prompted to create a passkey for faster and more secure future logins. If they choose to create it, their device’s fingerprint scanner or security key is registered.

2. If the user has a passkey registered

This workflow applies to users with an existing passkey.

Steps

1. Enter login: The user provides their username or email.
2. Propose to authenticate using the passkey: The system detects the presence of a registered passkey and offers this as the primary option.
   • Options:
     • Use passkey: The user proceeds with passkey authentication. The system sends the challenge to the user’s device, and the authentication completes upon signature verification.
     • Switch to password: The user can choose to fall back to password authentication if the passkey method is unavailable (e.g., device not accessible).

Passkey authentication technical diagram

The relying party is the eQual backend API, it proposes 2 endpoints for passkey authentication:

• get=user_passkey-auth-options
• do=user_passkey-auth

The authentication options are defined by the following passkey settings:

• Allowed formats: android-key, android-safetynet, apple, fido-u2f, none, packed, tpm
• User verification: required, preferred, discourage
• Cross-platform: all, cross-platform, platform
• Allowed authenticators: USB, NFC, BLE, Hybrid, Internal

Example:

A returning user opens their shopping app. They enter their username and are prompted to authenticate using their registered passkey. With a tap on their phone’s fingerprint scanner, they quickly gain access. Alternatively, they can switch to entering their password if their device is unavailable.

Controllers

DATA

user_passkey-register-options

Returns the data needed for passkey registration:

• a challenge that the authenticator will have to sign
• a unique/randomly-generated user handle
• register options depending on settings:
  • relying party id
  • relying party name
  • is user verification enabled
  • cross-platform option
  • allowed attestation formats

user_passkey-auth-options

Returns the data needed for passkey authentication:

• user credential ids
• register options depending on settings:
  • relying party id
  • relying party name
  • is user verification enabled
  • cross-platform option
  • allowed attestation formats
  • allowed authenticators

ACTIONS

user_passkey-register

Registers a passkey to access the eQual application:

• check that given challenge is correctly signed
• create a passkey
  • store the given public key
  • store the credential id

user_passkey-auth

Authenticates using a passkey:

• check that given challenge is correctly signed
• check that the given passkey data are matching the database's

It returns an access token cookie on successful authentication.

Settings

A series of settings allows to configure the passkey registration and authentication processes.

Propose passkey creation

Toggle to enable or disable passkey creation prompt. This ensures users are offered the ability to create passkeys during their authentication process.

Passkey relying party ID

The domain name used as the relying party ID. For example "localhost" or "my-app.org" . This acts as the unique identifier for the website or application.

Passkey relying party name

A user-friendly name for the relying party. For example, "MyApp" or "SecureBank" to help users recognize the entity they are authenticating with.

Passkey Format Enable

Enable or disable attestation formats supported by WebAuthn during credential creation or authentication. In the Web Authentication API, attestation refers to the process of providing proof about the authenticity of a credential and its security properties. This is important for verifying that the credential was created in a secure environment, such as a hardware security module or a trusted execution environment.

Supported formats:

• android-key: Used for Android devices with a key-based implementation.
• android-saftynet: Enables Google's SafetyNet attestation for Android.
• apple: Compatibility with Apple's WebAuthn implementation.
• fido-u2f: Universal Second Factor standard for security keys.
• none: Disables attestation formats.
• packed: Combines multiple attestation techniques into a single format.
• tpm: Trusted Platform Module-based attestation.

Passkey User Verification

Passkey User Verification is a critical step in the Web Authentication (WebAuthn) framework to ensure that only the authorized user can use a credential to authenticate. It involves verifying the user locally on their device before allowing them to proceed with authentication using a passkey.

Options:

• required: Enforces biometric or PIN-based user verification.
• preferred: Recommends but does not require verification.
• discouraged: Skips user verification during authentication.

Passkey Cross-Platform

Cross-Platform Passkeys are a feature of the Web Authentication (WebAuthn) API that allow users to use passkeys across devices, operating systems, and platforms. This capability is made possible by syncing passkeys securely through cloud services, enabling a seamless and passwordless experience regardless of the device a user is on.

Options:

• all: Allows both platform-specific and cross-platform authenticators.
• cross-platform: Prioritizes cross-platform devices like external security keys.
• platform: Limits usage to platform authenticators, such as device-specific biometrics.

Passkey Authenticator

A Passkey Authenticator is a device or platform that securely stores and manages passkeys, enabling passwordless login through Web Authentication (WebAuthn). Authenticators are a critical component of the WebAuthn API, as they perform the cryptographic operations required for passkey authentication.

Supported authenticators:

• USB: Security keys connected via USB.
• NFC: Near-field communication-enabled security keys.
• BLE: Bluetooth-enabled authenticators.
• Hybrid: Authenticators supporting multiple communication methods.
• Internal: Built-in authenticators like Touch ID or Windows Hello.