---
title: Authentication System
description: This guide explains how to use the user authentication system of LibreChat, which offers secure and easy email and social logins. You will learn how to set up sign up, log in, password reset, and more.
--- 

# Basic Configuration:

## 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', 'Enable or disable ONLY email login.','ALLOW_EMAIL_LOGIN=true'],
    ['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 does not support the ability to disable only registration.

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.



<div style={{display: "flex", justifyContent: "center", alignItems: "center", flexDirection: "column"}}>
  <div className="image-light-theme">
    ![register-light](https://github.com/danny-avila/LibreChat/assets/32828263/4c51dc25-31d3-4c51-8c2a-0cdfb5a25033)
  </div>

  <div className="image-dark-theme">
    ![register](https://github.com/danny-avila/LibreChat/assets/32828263/3bc5371d-e51d-4e91-ac68-56db6e85bb2c)
  </div>
</div>


## 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

- You should use new secure values. The examples given are 32-byte keys (64 characters in hex). 
  - Use this tool to generate some quickly: **[JWT Keys](/toolkit/creds_generator)**

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

---

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

2. For the deploy-compose.yml:
   ```
   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:
   ```
   docker-compose exec api npm run delete-user email@domain.com
   ```

2. For the deploy-compose.yml:
   ```
   docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run delete-user email@domain.com"
   ```

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

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

