diff --git a/pages/docs/configuration/authentication/passkey.mdx b/pages/docs/configuration/authentication/passkey.mdx new file mode 100644 index 00000000..bdee1882 --- /dev/null +++ b/pages/docs/configuration/authentication/passkey.mdx @@ -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: + + + +Additionally, ensure **social login and registration** are enabled: + + + +> **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.** diff --git a/pages/docs/configuration/dotenv.mdx b/pages/docs/configuration/dotenv.mdx index 6a6e5e71..36df635c 100644 --- a/pages/docs/configuration/dotenv.mdx +++ b/pages/docs/configuration/dotenv.mdx @@ -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)** + + + + #### [OpenID Connect](/docs/configuration/authentication/OAuth2-OIDC#openid-connect) For more information: