A LiveComponent for authentication via WebAuthn API.

Authentication = Sign In

Authentication is the process of matching a registered key to an existing user.

With Passkeys, the user is presented with a native modal from the browser or OS.

• If the user has only one passkey registered to the application's origin URL, they will be prompted to confirm acceptance via biometric ID (touch, face, etc.), OS password, or an OS PIN.
• If multiple accounts are registered to the device for the origin URL, the user may select an account to use for the current session.

Cross-Device Authentication

When a user attempts to authenticate on a device where their Passkey is not stored, they may scan a QR code to use a cloud-sync'd Passkey.

Example

Imagine a user, Amal, registers a Passkey for example.com on their iPhone and it's stored in iCloud. When they attempt to sign into example.com on a non-Apple device or any browser which cannot access their OS keychain, they may choose to scan a QR code using their iPhone. Assuming the prompts on the iPhone are successful, the other device will be authenticated using the same web account which was initially registered on the iPhone.

While this example refers to Apple's Passkey implementation, the process on other platforms may vary. Cross-device credential managers like 1Password may provide a more seamless flow for users who are not constrained to one OS or browser.

Assigns

• @challenge: (Internal) A Wax.Challenge struct created by the component, used to request an existing credential in the client.
• @display_text (Optional) The text displayed inside the button. Defaults to "Sign In".
• @show_icon? (Optional) Controls visibility of the key icon. Defaults to true.
• @class (Optional) CSS classes for overriding the default button style.
• @disabled (Optional) Set to true when the SupportHook indicates WebAuthn is not supported or enabled by the browser. Defaults to false.
• @id (Optional) An HTML element ID.

Events

• "authenticate": Triggered when a user clicks the authenticate button.
• "authentication-challenge": Sent from the component to the client to request an existing credential registered to the endpoint URL.
• "authentication-attestation": Sent by the client when a credential has been registered to the endpoint URL and activated by the user.
• "error" Sent by the client when an error occurs.

Messages

• {:find_credential, key_id: key_id}

  • key_id is a raw binary representing the id stored associated with the credential in both the client and server during registration.
  • The parent LiveView must successfully lookup the user with this data before storing a token and redirecting to another view.

• {:error, payload}

  • payload contains the message, name, and stack returned by the browser upon timeout or other client-side errors.

  Errors should be displayed to the user via Phoenix.LiveView.put_flash/3. However, some errors may be too technical or cryptic to be useful to users, so the parent LiveView may paraphrase the message for clarity.