webauthn_components

# WebauthnComponents

Passkey authentication for Phoenix LiveView applications.

- [WebauthnComponents](#webauthncomponents)
    - [Project Status](#project-status)
  - [Roadmap](#roadmap)
  - [Quick Start](#quick-start)
  - [Installation Details](#installation-details)
    - [Create a new Phoenix Project](#create-a-new-phoenix-project)
    - [Add the Dependency](#add-the-dependency)
    - [Generate and Modify Code](#generate-and-modify-code)
  - [Webauthn Flows](#webauthn-flows)
  - [WebAuthn and Passkeys](#webauthn-and-passkeys)
    - [Benefits](#benefits)
    - [Cross-Device Authentication](#cross-device-authentication)
      - [Example](#example)
    - [Known Issues](#known-issues)
  - [Browser Support](#browser-support)
  - [Additional Resources](#additional-resources)


### Project Status

- This package is a **work in progress**, and it is in early **beta** status.
- Please **do not use WebauthnComponents in a production environment** until it has completed _beta_ testing.
- Feel free to experiment with this package and contribute feedback in [Elixir Forum](https://elixirforum.com/t/webauthnlivecomponent-passwordless-auth-for-liveview-apps/49941).

## Roadmap

View the planned work for this repo in the public [WebauthnComponents v1](https://github.com/orgs/liveshowy/projects/3/views/1) project on GitHub.

## Quick Start

> The `wac.install` Mix Task is no longer supported as of v0.10.
> This task generated boilerplate code to ease initial setup, but its use was limited to greenfield apps.
>
> As of v0.10, scope is limited to credential registration and authentication.
> With this change, implementers may choose to follow CRUD, Event Sourcing, and other patterns based on an application's needs.

### Installation

Add the dependency to your `mix.exs` file:

```elixir
# my_app/mix.exs
def deps do
  [
    ...
    {:webauthn_components, "~> 0.10"}
  ]
end
```

Then, run `mix do deps.get + compile` to install and compile the dependency.

### Usage

Some decisions must be made when using WebauthnComponents. This package wraps the client-server coordination so that implementers can focus on the data model, business logic, and user experience.

On the backend, engineers and product owners may choose to follow the CRUD pattern for user and credential management. Event Sourcing may also by suitable when audit trails, evolving integrations, and data recovery are important.

The components in this package are designed to support a variety of user-facing authentication flows. An application may have separate registration and authentication pages, a consolidated page, and these features may be rendered directly in a global navbar. To manage credentials, it's common to have a section or page for user settings.

See component module documentation for examples, options, and messages which are passed to LiveView processes.

## Webauthn Flows

Documentation and illustrations for WebauthnComponent flows can be found in [Webauthn Flows](./webauthn_flows.md).

## WebAuthn and Passkeys

What is the difference between "WebAuthn" and "Passkeys"? The first is an API available in modern browsers, and the second is an implementation where public key credentials created by the WebAuthn API can be saved to the client device and/or a cloud provider.

The following quotes were chosen for their brevity and clarity.

From MDN:

> The Web Authentication API is an extension of the Credential Management API that enables strong authentication with public key cryptography, enabling passwordless authentication and/or secure second-factor authentication without SMS texts.
>
> https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API

From Google:

> A passkey is a FIDO login credential, tied to an origin (website or application) and a physical device. Passkeys allow users to authenticate without having to enter a username, password, or provide any additional authentication factor. This technology aims to replace passwords as the primary authentication mechanism.
>
> https://developers.google.com/identity/fido

\* While a user may *technically* be registered without a username or email, this is often a practical requirement for both a business and its users. By requiring an email, WebauthnComponents ensures each registered Passkey can be identified by the user when reviewing their collection of credentials. Email is often a required identifier for a business, especially when it needs to communicate with its users outside of its applications.

### Benefits

There are many benefits to users and application maintainers when passwords are decommissioned.

- Eliminates password reuse by users.
- Mitigates credential stuffing attacks by hackers.
- Eliminates phishing attacks by hackers.

For users on a device with Passkey support, WebAuthn credentials may be stored in the cloud. This allows the user to authenticate from other cloud-connected devices without registering each device individually.

### Cross-Device Authentication

Passkeys may be synchronized across mutliple devices connected to a user's cloud account, where credentials are managed.

- [iCloud Keychain on MacOS](https://developer.apple.com/passkeys/)
- [Android & Chrome](https://developers.google.com/identity/passkeys/supported-environments)
- [1Password](https://1password.com/product/passkeys)

When a user attempts to authenticate on a device where their Passkey is **not** synchronized, they may scan a QR code to use a Passkey stored on the registered device. The browser will detect that no Passkey is registered for the site and render the QR code to be scanned by the device where the Passkey can be accessed.

#### 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.

### Known Issues

While WebAuthn provides an API for improved authentication security, there are a few limitations to consider before adopting this component.

- As of 2026, Passkey support is supported in all modern browsers, with some caveats (see [Browser Support](#browser-support)).
- Cloud-synced credentials are only accessible to devices authenticated to the cloud account.
  - For example, a credential saved to iCloud Keychain will not be synced automatically to Android's credential manager.
  - 1Password has released Passkey support out of beta as of 9/2023.
  - Services like 1Password synchronize these credentials across platforms, but often require a subscription.
- If a user registers or authenticates on a device without Passkey support, the generated key pair will only function on the device where it was registered. Each device must be registered in order to access an account.

## Browser Support

With some caveats, the client-side WebAuthn API has broad support across modern browsers.

- https://caniuse.com/?search=webauthn

While this package is scoped to browser-based WebAuthn, it may be possible to use credentials in native/mobile applications with appropriate configuration.

- https://developer.apple.com/documentation/authenticationservices/supporting-passkeys
- https://developer.android.com/design/ui/mobile/guides/patterns/passkeys

## Additional Resources

- [Webauthn Guide](https://webauthn.guide/)
- MDN: [Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)
- FIDO: [FIDO2: Web Authentication (WebAuthn)](https://fidoalliance.org/fido2-2/fido2-web-authentication-webauthn/)
- W3: [Web Authentication: An API for accessing Public Key Credentials Level 2](https://www.w3.org/TR/webauthn-2/)
- Apple: [Passkeys Overview](https://developer.apple.com/passkeys/)