-
Notifications
You must be signed in to change notification settings - Fork 468
馃摎 docs: Document Recent Dev Changes and Rewrite Temporary Chat Retention #795
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鈥檒l occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
berry-13
wants to merge
2
commits into
main
Choose a base branch
from
berry-13/docs-update-latest
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| { | ||
| "title": "Authentication", | ||
| "icon": "Lock", | ||
| "pages": ["email", "ldap", "OAuth2-OIDC", "SAML"] | ||
| "pages": ["email", "passkeys", "ldap", "OAuth2-OIDC", "SAML"] | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,142 @@ | ||
| --- | ||
| title: Passkeys | ||
| icon: KeyRound | ||
| description: Let users sign in without a password using a device screen lock or a security key (WebAuthn). Covers enabling passkeys, the relying party settings, enrollment limits, and how passkeys interact with two-factor authentication. | ||
| --- | ||
|
|
||
| Passkeys let users with a local (email and password) account sign in with their device screen lock, a password manager, or a hardware security key instead of typing a password. LibreChat implements them with WebAuthn. They are off by default. | ||
|
|
||
| <Callout type="info" title="Availability"> | ||
| Newer than **v0.8.8**. Available now on LibreChat's `dev` and `canary` branches, and in the next release. | ||
| </Callout> | ||
|
|
||
| Use passkeys when you want a phishing-resistant, passwordless sign-in for local accounts. Accounts that sign in through OAuth, OpenID Connect, SAML, or LDAP keep using their provider and cannot add passkeys. | ||
|
|
||
| ## Enable passkeys | ||
|
|
||
| <Steps> | ||
| <Step> | ||
|
|
||
| **Serve LibreChat over HTTPS.** Browsers only allow WebAuthn in a secure context. `http://localhost` is exempt, so local testing works without TLS. | ||
|
|
||
| </Step> | ||
| <Step> | ||
|
|
||
| **Turn the feature on in `.env`.** For a standard deployment, this is the only required setting. The relying party ID and allowed origins are derived from `DOMAIN_CLIENT` and `DOMAIN_SERVER`. | ||
|
|
||
| ```bash filename=".env" | ||
| ALLOW_PASSKEY_LOGIN=true | ||
| ``` | ||
|
|
||
| </Step> | ||
| <Step> | ||
|
|
||
| **Pin the relying party ID (recommended).** Each passkey is permanently bound to the RP ID it was created under. If `DOMAIN_CLIENT` might ever change, set `PASSKEY_RP_ID` now so existing passkeys keep working. | ||
|
|
||
| ```bash filename=".env" | ||
| PASSKEY_RP_ID=chat.example.com | ||
| ``` | ||
|
|
||
| </Step> | ||
| <Step> | ||
|
|
||
| **Restart LibreChat.** The login page shows **Sign in with a passkey**, and **Settings > Account** shows a **Passkeys** section. | ||
|
|
||
| </Step> | ||
| </Steps> | ||
|
|
||
| ## Configuration reference | ||
|
|
||
| <OptionTable | ||
| options={[ | ||
| [ | ||
| 'ALLOW_PASSKEY_LOGIN', | ||
| 'boolean', | ||
| 'Enables passkey sign-in and the Passkeys section in account settings. Default: false.', | ||
| 'ALLOW_PASSKEY_LOGIN=true', | ||
| ], | ||
| [ | ||
| 'PASSKEY_RP_ID', | ||
| 'string', | ||
| 'Relying party ID: the domain passkeys are bound to. Must be a domain name (not an IP address) equal to, or a parent domain of, the host users visit. Defaults to the hostname of DOMAIN_CLIENT, or localhost.', | ||
| '# PASSKEY_RP_ID=chat.example.com', | ||
| ], | ||
| [ | ||
| 'PASSKEY_RP_NAME', | ||
| 'string', | ||
| 'Name the authenticator shows when creating or using a passkey. Defaults to APP_TITLE, then LibreChat.', | ||
| '# PASSKEY_RP_NAME=LibreChat', | ||
| ], | ||
| [ | ||
| 'PASSKEY_ORIGINS', | ||
| 'string', | ||
| 'Comma-separated list of origins allowed to run passkey ceremonies. Defaults to DOMAIN_CLIENT and DOMAIN_SERVER.', | ||
| '# PASSKEY_ORIGINS=https://chat.example.com', | ||
| ], | ||
| [ | ||
| 'MAX_PASSKEYS_PER_USER', | ||
| 'integer', | ||
| 'Passkeys each account may enroll, from 1 to 100. Overridden by passkeys.perUserMax in librechat.yaml. Default: 20.', | ||
| '# MAX_PASSKEYS_PER_USER=20', | ||
| ], | ||
| [ | ||
| 'PASSKEY_STEPUP_MAX', | ||
| 'integer', | ||
| 'Password-confirmed passkey add or remove attempts allowed per user in PASSKEY_STEPUP_WINDOW. Default: 20.', | ||
| 'PASSKEY_STEPUP_MAX=20', | ||
| ], | ||
| [ | ||
| 'PASSKEY_STEPUP_WINDOW', | ||
| 'integer', | ||
| 'Window in minutes for PASSKEY_STEPUP_MAX. Default: 15.', | ||
| 'PASSKEY_STEPUP_WINDOW=15', | ||
| ], | ||
| [ | ||
| 'PASSKEY_MAX', | ||
| 'integer', | ||
| 'Passkey sign-in requests allowed per IP in PASSKEY_WINDOW. One sign-in uses two requests. Requests over the limit get HTTP 429; they are not scored as violations because no user is signed in yet. Default: 20.', | ||
| '# PASSKEY_MAX=20', | ||
| ], | ||
| [ | ||
| 'PASSKEY_WINDOW', | ||
| 'integer', | ||
| 'Window in minutes for PASSKEY_MAX. Default: 5.', | ||
| '# PASSKEY_WINDOW=5', | ||
| ], | ||
| ]} | ||
| /> | ||
|
|
||
| ### Per-user limit in `librechat.yaml` | ||
|
|
||
| You can also set the enrollment cap in `librechat.yaml`: | ||
|
|
||
| ```yaml filename="librechat.yaml" | ||
| passkeys: | ||
| perUserMax: 10 | ||
| ``` | ||
|
|
||
| The cap resolves in this order: `passkeys.perUserMax` in `librechat.yaml`, then `MAX_PASSKEYS_PER_USER`, then the default of `20`. Values outside `1` to `100` are ignored and the next source is used. When a user reaches the cap, **Settings > Account** shows "You have reached the maximum number of passkeys". See [`passkeys`](/docs/configuration/librechat_yaml/object_structure/config#passkeys) in the config reference. | ||
|
|
||
| ## What users see | ||
|
|
||
| **Adding a passkey** | ||
|
|
||
| 1. Open **Settings > Account**, find **Passkeys**, and select **Manage**. | ||
| 2. Select **Add passkey**. | ||
| 3. Enter the account password in the **Confirm your password** dialog. A passkey is a complete sign-in on its own, so LibreChat asks for the password before creating one. | ||
| 4. Complete the browser or device prompt. The new passkey appears in the list with a default name such as **This device**, **Phone or tablet**, or **Security key**. | ||
|
|
||
| Each entry shows when it was added and last used, and a **Synced** badge when the authenticator reports that the passkey is backed up (for example, by a password manager). Users can rename a passkey, and removing one (**Remove passkey**) also asks for the account password. | ||
|
|
||
| **Signing in** | ||
|
|
||
| On the login page, users select **Sign in with a passkey** and approve the device prompt. If the account has two-factor authentication enabled, LibreChat still asks for the 2FA code afterward, exactly as it does after a password sign-in. | ||
|
|
||
| ## Behavior and caveats | ||
|
|
||
| - **Local accounts only.** Passkey enrollment and sign-in are limited to local accounts. Accounts created through an identity provider or LDAP must keep authenticating through that provider. | ||
| - **Works with email login disabled.** The **Sign in with a passkey** button and its routes depend only on `ALLOW_PASSKEY_LOGIN`. With `ALLOW_EMAIL_LOGIN=false`, existing local users can still sign in with passkeys they enrolled earlier. | ||
| - **Two-factor authentication.** Passkey sign-in goes through the same 2FA gate as password sign-in. With [`ENFORCE_TWO_FACTOR_AUTHENTICATION=true`](/docs/configuration/authentication#required-two-factor-authentication), a user who has not enrolled in 2FA is sent to the setup flow after signing in with a passkey. | ||
| - **Changing the RP ID orphans passkeys.** Passkeys created under one RP ID never work under another. Changing `PASSKEY_RP_ID`, or changing `DOMAIN_CLIENT` while `PASSKEY_RP_ID` is unset, leaves every existing passkey unusable; users must sign in another way and enroll again. | ||
| - **Origins must match.** If users reach LibreChat on an origin not covered by `PASSKEY_ORIGINS` (or the derived defaults), the browser shows "Passkeys are not available on this domain". Add every public origin to `PASSKEY_ORIGINS` when you serve LibreChat on more than one. | ||
| - **Password reset removes passkeys.** A completed password reset signs the account out everywhere and deletes all of its passkeys, so a passkey enrolled before the reset can no longer be used to get in. Users enroll again afterward. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For deployments that later move to an unrelated hostname, pinning
PASSKEY_RP_ID=chat.example.comdoes not keep existing passkeys working: WebAuthn requires the new origin's host to equal or be a subdomain of the pinned RP ID, so a move to a sibling such asnew.example.comor another domain makes ceremonies fail. Limit this recommendation to host changes within the RP ID's scope and explain that a stable parent domain must be chosen before enrollment when sibling-subdomain moves are expected.Useful? React with 馃憤聽/ 馃憥.