# Authentication System (https://www.librechat.ai/docs/configuration/authentication)

## General

For a quick overview, refer to the user guide provided here: [Authentication](/docs/features/authentication)

Here's an overview of the general configuration.

<OptionTable
  options={[
    [
      'ALLOW_EMAIL_LOGIN',
      'boolean',
      'Show email login and allow local or LDAP credential login through the authentication API.',
      'ALLOW_EMAIL_LOGIN=true',
    ],
    [
      'ALLOW_EMAIL_LOGIN_OVERRIDE',
      'boolean',
      'Allow direct credential requests to the login API while ALLOW_EMAIL_LOGIN is false. Default: false.',
      'ALLOW_EMAIL_LOGIN_OVERRIDE=false',
    ],
    [
      'ALLOW_REGISTRATION',
      'boolean',
      'Enable or disable email registration of new users.',
      'ALLOW_REGISTRATION=true',
    ],
    [
      'ALLOW_SOCIAL_LOGIN',
      'boolean',
      'Allow users to connect to LibreChat with various social networks.',
      'ALLOW_SOCIAL_LOGIN=false',
    ],
    [
      'ALLOW_SOCIAL_REGISTRATION',
      'boolean',
      'Enable or disable registration of new users using various social networks.',
      'ALLOW_SOCIAL_REGISTRATION=false',
    ],
  ]}
/>

> **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](#create-user-script) detailed below.
- To delete a user, you can use [the delete-user script](#delete-user-script) also detailed below.

<ThemeImage
  light="https://github.com/danny-avila/LibreChat/assets/32828263/4c51dc25-31d3-4c51-8c2a-0cdfb5a25033"
  dark="https://github.com/danny-avila/LibreChat/assets/32828263/3bc5371d-e51d-4e91-ac68-56db6e85bb2c"
  alt="User registration screen"
/>

## Session Expiry and Refresh Token

- Default values: session expiry: 15 minutes, refresh token expiry: 7 days
  - For more information: **[GitHub PR #927 - Refresh Token](https://github.com/danny-avila/LibreChat/pull/927)**

<OptionTable
  options={[
    ['SESSION_EXPIRY', 'integer (milliseconds)', 'Session expiry time.','SESSION_EXPIRY=1000 * 60 * 15'],
    ['REFRESH_TOKEN_EXPIRY', 'integer (milliseconds)', 'Refresh token expiry time.','REFRESH_TOKEN_EXPIRY=(1000 * 60 * 60 * 24) * 7'],
  ]}
/>

``` mermaid
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](/toolkit/creds_generator), store them securely, and provide the same values to every LibreChat replica.

<OptionTable
  options={[
    ['JWT_SECRET', 'string (hex)', 'JWT secret key.','JWT_SECRET='],
    ['JWT_REFRESH_SECRET', 'string (hex)', 'JWT refresh secret key.','JWT_REFRESH_SECRET='],
  ]}
/>

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](/docs/configuration/dotenv#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](/docs/configuration/mod_system).

> *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):
   ```bash
   docker compose exec api npm run create-user
   ```

2. For the `deploy-compose.yml` (if you followed the [Ubuntu Docker Guide](/docs/remote/docker_linux)):
   ```bash
   docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run create-user"
   ```

3. For local development (from project root):
   ```bash
   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):
   ```bash
   docker compose exec api npm run delete-user email@domain.com
   ```

2. For the `deploy-compose.yml` (if you followed the [Ubuntu Docker Guide](/docs/remote/docker_linux)):
   ```bash
   docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run delete-user email@domain.com"
   ```

3. For local development (from project root):
   ```bash
   npm run delete-user email@domain.com
   ```

Replace `email@domain.com` with the email of the user you want to delete.