Authentication System

General

For a quick overview, refer to the user guide provided here: Authentication

Here's an overview of the general configuration.

Note: OpenID and SAML do not support the ability to disable only registration.

Setting ALLOW_EMAIL_LOGIN=false hides the email login form and rejects local or LDAP credential requests to /api/auth/login; OAuth, OpenID Connect, and SAML sign-in are unaffected. ALLOW_EMAIL_LOGIN_OVERRIDE=true is intended only for a controlled API integration that still needs credential login while the form is hidden. Every override use logs the request IP, so protect and monitor that route carefully.

Quick Tips:

• Even with registration disabled, you can add users directly to the database using the create-user script detailed below.
• To delete a user, you can use the delete-user script also detailed below.

Related sign-in options for local accounts:

• Passkeys: passwordless sign-in with a device screen lock or security key (ALLOW_PASSKEY_LOGIN).
• Email address change: lets users change their registered email from Settings > Account (ALLOW_EMAIL_CHANGE, on by default).

Required Two-Factor Authentication

Users can always turn on two-factor authentication (TOTP) themselves from Settings > Account. To make it mandatory, set:

ENFORCE_TWO_FACTOR_AUTHENTICATION=true

Who it applies to: local (email and password) and LDAP accounts. Accounts that sign in through OAuth, OpenID Connect, or SAML are not affected, because their identity provider is responsible for MFA. A federated account that tries to sign in with a password while enforcement is on is told to use its identity provider instead.

What users see: a user without 2FA who signs in (with a password, LDAP credentials, or a passkey) gets no session until setup is complete. They land on a Two-Factor Authentication Required screen ("Your administrator requires two-factor authentication. Set it up before continuing."), scan a QR code with an authenticator app, enter a code to verify, and save their backup codes. Users who are already signed in are moved into the same setup the next time their session is checked or refreshed, and access tokens issued before enrollment stop working. The setup session lasts 10 minutes; if it expires, the user returns to the login page and starts again.

After enrollment: the Disable 2FA control in Settings > Account shows Required by administrator, and the server rejects attempts to disable 2FA while the policy is on. Users can still regenerate backup codes.

Session Expiry and Refresh Token

• Default values: session expiry: 15 minutes, refresh token expiry: 7 days
  • For more information: GitHub PR #927 - Refresh Token

sequenceDiagram
    Client->>Server: Login request with credentials
    Server->>Passport: Use authentication strategy (e.g., 'local', 'google', etc.)
    Passport-->>Server: User object or false/error
    Note over Server: If valid user...
    Server->>Server: Generate access and refresh tokens
    Server->>Database: Store hashed refresh token
    Server-->>Client: Access token and refresh token
    Client->>Client: Store access token in HTTP Header and refresh token in HttpOnly cookie
    Client->>Server: Request with access token from HTTP Header
    Server-->>Client: Requested data
    Note over Client,Server: Access token expires
    Client->>Server: Request with expired access token
    Server-->>Client: Unauthorized
    Client->>Server: Request with refresh token from HttpOnly cookie
    Server->>Database: Retrieve hashed refresh token
    Server->>Server: Compare hash of provided refresh token with stored hash
    Note over Server: If hashes match...
    Server-->>Client: New access token and refresh token
    Client->>Server: Retry request with new access token
    Server-->>Client: Requested data

JWT Secret and Refresh Secret

Use unique values of at least 32 bytes. Generate permanent values with the Credentials Generator, store them securely, and provide the same values to every LibreChat replica.

When either value is blank, LibreChat can generate and reuse a value from its temporary credentials file. The default Docker Compose stacks persist that file, but this is intended only as a bootstrap convenience. If the file is lost or cannot be written, sessions can become invalid after restart. See Credentials Configuration for precedence, persistence, and production guidance.

Automated Moderation System (optional)

The Automated Moderation System is enabled by default. It uses a scoring mechanism to track user violations. As users commit actions like excessive logins, registrations, or messaging, they accumulate violation scores. Upon reaching a set threshold, the user and their IP are temporarily banned. This system ensures platform security by monitoring and penalizing rapid or suspicious activities.

To set up the mod system, review the setup guide.

Please Note: If you want this to work in development mode, you will need to create a file called .env.development in the root directory and set DOMAIN_CLIENT to http://localhost:3090 or whatever port is provided by vite when runnning npm run frontend-dev

User Management Scripts

Create User Script

The create-user script allows you to add users directly to the database, even when registration is disabled. Here's how to use it:

1. For the default docker-compose.yml (if you use docker compose up to start the app):

   docker compose exec api npm run create-user

2. For the deploy-compose.yml (if you followed the Ubuntu Docker Guide):

   docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run create-user"

3. For local development (from project root):

   npm run create-user

Follow the prompts to enter the new user's email and password.

Delete User Script

To delete a user, you can use the delete-user script:

1. For the default docker-compose.yml (if you use docker compose up to start the app):

   docker compose exec api npm run delete-user [email protected]

2. For the deploy-compose.yml (if you followed the Ubuntu Docker Guide):

   docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run delete-user [email protected]"

3. For local development (from project root):

   npm run delete-user [email protected]

Replace [email protected] with the email of the user you want to delete.