Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added Passkey documentation page #215

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 106 additions & 0 deletions pages/docs/configuration/authentication/passkey.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
---
title: Passkey
description: Learn how to enable and configure Passkey authentication in LibreChat for passwordless login.
---

# Passkey Authentication Setup

Passkeys provide a **passwordless authentication** experience using WebAuthn. This guide explains how to enable, configure, and use **Passkey authentication** in **LibreChat**.

## 1. Configuration

Passkey authentication requires the following environment variables to be configured in your `.env` file.

### Basic Configuration

To enable **Passkey authentication**, set these environment variables:

<OptionTable
options={[
['PASSKEY_ENABLED', 'boolean', 'Enable or disable Passkey authentication.', 'PASSKEY_ENABLED=true'],
['RP_ID', 'string', 'The relying party ID (RP ID) which should match your domain name (without http:// or https://).', 'RP_ID=localhost'],
]}
/>

Additionally, ensure **social login and registration** are enabled:

<OptionTable
options={[
['ALLOW_SOCIAL_LOGIN', 'boolean', 'Enable social login options.', 'ALLOW_SOCIAL_LOGIN=true'],
['ALLOW_SOCIAL_REGISTRATION', 'boolean', 'Enable social registration options.', 'ALLOW_SOCIAL_REGISTRATION=true'],
]}
/>

> **Note:** The `RP_ID` must match your domain (e.g., `example.com`) and should not include `http://` or `https://`.

---

## 2. Passkey Authentication Workflow

### Login Process
1. **User enters their email** in the login screen.
2. **Browser prompts Passkey authentication** (Face ID, Touch ID, security key, or device authentication).
3. **User verifies using biometrics or a security key**.
4. **The passkey response is sent to the backend for verification**.
5. **If successful, the user is logged in** without needing a password.

### Registration Process
1. **User enters their email** in the registration screen.
2. **A passkey challenge is generated and sent to the browser**.
3. **User verifies using biometrics or a security key**.
4. **The passkey is stored on the user’s device**.
5. **If successful, the user is registered without a password**.

---

## 3. User Interface Updates

### Login Page Enhancements
- Users can log in using a Passkey instead of a password.
- If a passkey is available, the browser will prompt biometric authentication.

### Registration Page Enhancements
- Users can register using Passkeys.
- If supported, their browser will prompt them to save a passkey.

### Account Settings
- Users can view and manage their saved passkeys.
- Passkeys can be removed from their profile if necessary.

---

## 4. Security Considerations

- **Passkeys should only be used over HTTPS** (except for `localhost` in development).
- **RP ID must match the deployment domain** to prevent phishing.
- **Multi-device Passkeys are supported** (Google Password Manager, iCloud Keychain, etc.).
- **Users should have an option to delete Passkeys** from their account settings.

---

## 5. Screenshots

The following images illustrate the Passkey login and registration process in LibreChat:

| Feature | Screenshot |
|-----------------------|------------------------------------------|
| Login Page | ![Login](https://github.com/user-attachments/assets/035cb86a-c776-412f-87d5-e6b712b6987f) |
| Passkey Login | ![Login Passkey](https://github.com/user-attachments/assets/80158d2e-7170-476e-b341-021a8ee19c15) |
| Passkey Authentication | ![Passkey Account](https://github.com/user-attachments/assets/d6dcdfee-758e-4113-95a8-2754ad57faad) |
| Registration Page | ![Register](https://github.com/user-attachments/assets/8faaa799-d6fb-49e9-9fcc-3a47bee44954) |
| Passkey Register | ![Register Passkey](https://github.com/user-attachments/assets/6bdc1339-b1fc-4901-871d-0ca1fae744e9) |
| Passkey Registration | ![Passkey Registration](https://github.com/user-attachments/assets/937207f8-7738-4724-8ea8-7e6e1921246a) |
| Account Settings | ![Account](https://github.com/user-attachments/assets/9a6e75f0-f955-46aa-9154-4c25b7331cfc) |
| View Passkeys | ![Passkeys](https://github.com/user-attachments/assets/e1a4e7e4-d231-4292-aadc-f90db166ee7e) |

---

## 6. Testing Your Setup

To ensure Passkey authentication works correctly:

1. **Enable Passkeys in `.env`** (`PASSKEY_ENABLED=true`).
2. **Restart the server** for changes to take effect.
3. **Open the login or registration page**.
4. **Attempt Passkey authentication** using Face ID, Touch ID, or a security key.
5. **Verify login and registration success.**
13 changes: 13 additions & 0 deletions pages/docs/configuration/dotenv.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -808,6 +808,19 @@ For more information: **[Google Authentication](/docs/configuration/authenticati
]}
/>


#### [Passkey Authentication](/docs/configuration/authentication/passkey)

For more information: **[Passkey Authentication](/docs/configuration/authentication/passkey)**

<OptionTable
options={[
['PASSKEY_ENABLED', 'boolean', 'Enable or disable Passkey authentication.', 'PASSKEY_ENABLED=true'],
['RP_ID', 'string', 'The relying party ID, which should match your domain (without http:// or https://).', 'RP_ID=localhost'],
]}
/>


#### [OpenID Connect](/docs/configuration/authentication/OAuth2-OIDC#openid-connect)

For more information:
Expand Down
Loading