PasskeySettings Documentation

Overview

The PasskeySettings component serves as a user interface for managing passkeys, an advanced authentication method that provides enhanced security over traditional passwords. This component allows users to register and manage their biometric authentication methods (e.g., Face ID, Touch ID) or security keys, streamlining the sign-in process across devices.

Purpose

The purpose of the PasskeySettings component is to facilitate the following functionalities:

1. Registration of Passkeys: Users can register new passkeys, enabling biometric or security key authentication.
2. Management of Existing Passkeys: Users can view, rename, or delete existing passkeys.
3. Display of Status Messages: It provides feedback to users when actions are taken, such as successful registration or errors.

Settings

The PasskeySettings component utilizes several internal states to manage its behavior. Each setting represents a key piece of functionality within the component.

1. passkeys

• Input Type: Array of objects
• Description: Stores a list of registered passkeys retrieved from the backend. Each passkey object contains details such as id, device_name, backed_up, created, and last_used.
• Default Value: [] (empty array)
• Behavior: Displayed in a list format; the user can interact with these passkeys (e.g., rename or delete them).

2. loading

• Input Type: Boolean
• Description: Indicates whether the passkeys are currently being loaded from the server.
• Default Value: true
• Behavior: While true, a loading state UI is shown; switches to false after successful data fetch.

3. registering

• Input Type: Boolean
• Description: Indicates if a passkey registration process is ongoing.
• Default Value: false
• Behavior: If true, it shows a loading spinner while waiting for user confirmation or biometric input.

4. deviceName

• Input Type: String
• Description: Stores the name of the device being registered as a passkey. It is editable by the user.
• Default Value: '' (empty string)
• Behavior: Used to optionally label the passkey during registration.

5. showNameInput

• Input Type: Boolean
• Description: Controls whether the input field for the device name is visible during the registration process.
• Default Value: false
• Behavior: When true, the input field allows users to specify a name for the passkey.

6. error

• Input Type: String
• Description: Stores error messages related to interactions with passkeys (e.g., registration failures).
• Default Value: '' (empty string)
• Behavior: Displays the error message to the user if any error occurs during operations.

7. success

• Input Type: String
• Description: Stores success messages related to user interactions, such as successful registrations or deletions.
• Default Value: '' (empty string)
• Behavior: Provides visual feedback to the user upon successful actions.

8. editingId

• Input Type: Number or null
• Description: Keeps track of the currently editing passkey's ID if the user wants to rename it.
• Default Value: null
• Behavior: If not null, this ID indicates which passkey is being edited, enabling the rename input field.

9. editName

• Input Type: String
• Description: Holds the new name for the passkey while it is being edited.
• Default Value: '' (empty string)
• Behavior: Binds to the input field for renaming a passkey, allowing users to change its name.

How It Works

Data Flow

1. The component initializes by fetching existing passkeys from the API endpoint /api/user/passkeys on mount.
2. Users can register a new passkey by calling the API to get registration options, which triggers the browser's biometric authentication prompt.
3. Upon successful registration, the device name is sent along with the biometric response to the server for verification.
4. Users can delete or rename existing passkeys via respective API endpoints, with UI updates reflecting these changes in real-time.

API Interaction

The component leverages three major API endpoints for its operations:

• GET /api/user/passkeys: Fetches all user-associated passkeys.
• POST /api/auth/passkey/register-options: Requests registration options for a new passkey.
• POST /api/auth/passkey/register-verify: Verifies the registered passkey against the input received from the user.
• DELETE /api/user/passkeys: Removes a specified passkey.
• PUT /api/user/passkeys: Renames a specified passkey.

Use Cases & Examples

Use Case 1: Enhanced Security for Enterprise Users

An enterprise organization wishes to improve security by offering biometric logins for employee accounts. By implementing passkey-based authentication through the PasskeySettings component, every employee can enable same-device biometric verification methods, ensuring secure access without traditional passwords.

Use Case 2: Account Recovery and Management

A user frequently changes devices and needs to manage multiple passkeys effectively. The PasskeySettings component allows them to easily add, delete, or rename passkeys across devices, managing their authentication methods in one place.

Example Configuration

Scenario

A user wants to register a new passkey for their iPhone, which is to be used for secure sign-in to their services.

Configuration Steps

1. The user clicks on the "Add a passkey" button.
2. The input field for the device name appears; the user types "iPhone".
3. The user is prompted for biometric authentication (e.g., Face ID).
4. Upon successful authentication, the passkey is registered and the UI is updated to reflect the addition.

Sample Configuration Data

{
    "deviceName": "iPhone",
    "action": "register"
}

The PasskeySettings component effectively integrates user-friendly functionality that enhances security through seamless passkey management, providing necessary feedback to users during the process.