Terminology
Key terminology used across the Passlock documentation:
Autofill
Section titled “Autofill”Allows the browser to use a passkey for login if a suitable passkey is available on the device, otherwise falling back to an alternative login mechanism. Useful when some users have passkeys and others are still using username/password authentication.
Passlock adopts a protocol similar to OpenID Connect. Your frontend code uses the @passlock/client library to authenticate a user. This results in a code which you send to your backend. Your backend then exchanges this code for details about the passkey via the @passlock/node library, or via a REST call to the Passlock REST API. See also id_token.
Challenge
Section titled “Challenge”Passkeys are built on public key technology (similar to SSL/TLS). Private keys are never transmitted, in fact there is no way to programmatically access a private key. Instead we generate random challenges, and ask the device to sign them using a private key. To verify a passkey login, we verify the signature using the corresponding public key, which is held in the Passlock vault.
ID Token
Section titled “ID Token”Along with a code, the Passlock client library also returns an id_token (a signed JWT). You can use the @passlock/node library or any suitable JWT library to verify the token and obtain details about the passkey used.
Passkey
Section titled “Passkey”Strictly, a passkey is a Web Authentication API (aka WebAuthn) Credential with specific requirements. Put simply a Passkey is a credential that can be stored on a device (as opposed to a dedicated, standalone hardware key) and synced across devices.
A passkey is composed of a public and private key, and Passlock stores the public key in your vault. The private key remains on the user’s device but may be synced with other devices. This is a platform/OS concern.
Passkey syncing
Section titled “Passkey syncing”One feature of passkeys vs general WebAuthn credentials is the ability to sync credentials across devices. For example a passkey registered on an iPhone will be available on other devices sharing the same iCloud account. See also roaming authenticator
Primary authentication
Section titled “Primary authentication”Using a passkey as the first/sole authentication mechanism e.g. a user visits your site, then selects “login with passkey”.
Roaming authenticator
Section titled “Roaming authenticator”Signing into a website or app on device B, using a passkey registered on device A. Unlike a synced passkey, the passkey is not downloaded onto device B, instead authentication is temporarily delegated to device A.
Related Origin requests
Section titled “Related Origin requests”Related origin requests allow passkey authentication across domains when both domains explicitly and verifiably agree to trust each other. This opens up a few very important possibilities:
-
Domain name migration e.g. oldsite.com -> newsite.com
-
Related (group) domains e.g. using a single passkey for mysite.com, mysite.co.uk and mysite.ie
Passkeys are resistant to phishing attacks because a passkey registered for use on example.com cannot be presented on attacker.com, even if the user wants to do so. The device simply won’t allow it.
Browsers know which website a passkey can be presented on because each passkey is associated with a Relying Party Identifier, which is essentially the domain name of the website the passkey was registered on.
There are some rules around how browsers should treat the rpID:
A passkey registered to example.com can be presented to example.com and login.example.com, but a passkey registered to login.example.com cannot be presented to example.com.
There is one exception to this rule, known as related origin requests - which allow two related domains to share passkeys.
Secondary authentication
Section titled “Secondary authentication”The user uses a passkey in addition to another form of authentication. e.g. they first login with their username/password, then they are prompted for their passkey.
Signals
Section titled “Signals”A mechanism by which developers can manage passkeys on a device e.g. deleting a passkey or changing the username/display name.
Step-up authentication
Section titled “Step-up authentication”When a user, who is currently authenticated is asked to re-authenticate with their passkey. Typically used for sensitive operations e.g. changing a password, email address or payment details.
Tenancy
Section titled “Tenancy”Your Passlock cloud instance includes multiple “tenancies” - independent, isolated environments. Passkeys, users, logs etc are all stored in a specific tenancy. The tenancyId identifies a specific tenancy.
Two-step authentication
Section titled “Two-step authentication”When the login process is split into two steps / screens. The user is first asked for their account identifier, then they are asked for their credentials. The advantage of this mechanism is that as a developer, you know which authentication options to present to the user. Can be a good alternative to autofill.
User verification
Section titled “User verification”During passkey registration or authentication, you can request the device to re-authenticate a user locally by a suitable means. This is typically performed on the device using facial recognition or fingerprint verification. If biometric authentication is not available, the user may be prompted to authenticate using a device passcode.
Relying Parties (your web app) can check if the user was re-authenticated locally.
During passkey registration, the @passlock/client library will ask the browser/device to generate a Web Authentication API credential, composed of a public/private keypair. The private key remains on the user’s device and the public key is stored in your tenancy-specific “Vault”.
During authentication the browser/device will sign a challenge using a private key. Our client library will send it to the Passlock backend for verification. During verification we’ll pass the challenge response to the vault and it will be verified using the associated public key.