Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danny-avila/LibreChat/llms.txt

Use this file to discover all available pages before exploring further.

LibreChat supports multiple authentication strategies to accommodate various organizational requirements. This guide covers setup for local email authentication, OAuth2 providers, LDAP, OpenID Connect, and SAML.

​
Authentication Strategies Overview

LibreChat implements authentication through Passport.js strategies located in api/strategies/. The following authentication methods are available:
  • Local Strategy (Email/Password)
  • OAuth2 Providers (Google, GitHub, Discord, Facebook, Apple)
  • LDAP (Lightweight Directory Access Protocol)
  • OpenID Connect
  • SAML (Security Assertion Markup Language)

​
Local Email/Password Authentication

Local authentication is enabled by default and uses email/password credentials stored in MongoDB.

​
Configuration

1

Set JWT Secrets

Generate secure JWT secrets for session management:
.env
JWT_SECRET=your-secure-random-secret-key
JWT_REFRESH_SECRET=your-secure-refresh-secret-key
Generate secure secrets using: openssl rand -hex 32
2

Configure Session Expiry

Set session and refresh token expiration times:
.env
SESSION_EXPIRY=1000 * 60 * 15  # 15 minutes
REFRESH_TOKEN_EXPIRY=(1000 * 60 * 60 * 24) * 7  # 7 days
3

Email Verification Settings

Configure email verification requirements:
.env
ALLOW_UNVERIFIED_EMAIL_LOGIN=false
ALLOW_PASSWORD_RESET=true
When ALLOW_UNVERIFIED_EMAIL_LOGIN=false, users must verify their email before logging in. Ensure email service is configured.
4

Set Password Requirements

Configure minimum password length:
.env
MIN_PASSWORD_LENGTH=8

​
Local Strategy Implementation

The local strategy (api/strategies/localStrategy.js) validates credentials and handles email verification:
api/strategies/localStrategy.js
const { Strategy: PassportLocalStrategy } = require('passport-local');

module.exports = () =>
  new PassportLocalStrategy(
    {
      usernameField: 'email',
      passwordField: 'password',
      session: false,
      passReqToCallback: true,
    },
    passportLogin,
  );

​
OAuth2 Authentication

LibreChat supports multiple OAuth2 providers for social login.

​
Enable Social Login

.env
ALLOW_SOCIAL_LOGIN=true
ALLOW_SOCIAL_REGISTRATION=true

​
Google OAuth2

1

Create Google OAuth Credentials

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Navigate to APIs & Services > Credentials
  4. Click Create Credentials > OAuth 2.0 Client ID
  5. Configure the consent screen
  6. Add authorized redirect URI: http://your-domain:3080/oauth/google/callback
2

Configure Environment Variables

.env
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=/oauth/google/callback
DOMAIN_SERVER=http://localhost:3080

​
GitHub OAuth2

1

Register GitHub OAuth App

  1. Go to GitHub Settings > Developer settings > OAuth Apps
  2. Click New OAuth App
  3. Set Authorization callback URL: http://your-domain:3080/oauth/github/callback
2

Configure Environment Variables

.env
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_CALLBACK_URL=/oauth/github/callback
For GitHub Enterprise:
.env
GITHUB_ENTERPRISE_BASE_URL=https://github.your-company.com
GITHUB_ENTERPRISE_USER_AGENT=LibreChat

​
Discord OAuth2

.env
DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret
DISCORD_CALLBACK_URL=/oauth/discord/callback

​
Facebook OAuth2

.env
FACEBOOK_CLIENT_ID=your-facebook-app-id
FACEBOOK_CLIENT_SECRET=your-facebook-app-secret
FACEBOOK_CALLBACK_URL=/oauth/facebook/callback

​
Apple OAuth2

.env
APPLE_CLIENT_ID=your-apple-service-id
APPLE_TEAM_ID=your-apple-team-id
APPLE_KEY_ID=your-apple-key-id
APPLE_PRIVATE_KEY_PATH=/path/to/private-key.p8
APPLE_CALLBACK_URL=/oauth/apple/callback

​
LDAP Authentication

LDAP authentication enables integration with Active Directory or other LDAP servers.

​
Prerequisites

  • Access to an LDAP server
  • LDAP bind credentials (optional, for search operations)
  • User search base DN

​
Configuration

1

Set LDAP Server URL

.env
LDAP_URL=ldap://ldap.example.com:389
# or for LDAPS
LDAP_URL=ldaps://ldap.example.com:636
2

Configure Bind Credentials

Set the bind DN and credentials for search operations:
.env
LDAP_BIND_DN=cn=admin,dc=example,dc=com
LDAP_BIND_CREDENTIALS=your-ldap-password
If your LDAP server allows anonymous bind, these can be omitted.
3

Set User Search Base

Define where to search for users:
.env
LDAP_USER_SEARCH_BASE=ou=users,dc=example,dc=com
LDAP_SEARCH_FILTER=mail={{username}}
Common search filters:
  • mail={{username}} - Search by email
  • uid={{username}} - Search by UID
  • sAMAccountName={{username}} - Search by Windows username
4

Configure Attribute Mapping

Map LDAP attributes to user fields:
.env
LDAP_ID=uid
LDAP_USERNAME=uid
LDAP_EMAIL=mail
LDAP_FULL_NAME=cn,displayName
5

SSL/TLS Configuration

For secure LDAP connections:
.env
LDAP_CA_CERT_PATH=/path/to/ca-certificate.pem
LDAP_TLS_REJECT_UNAUTHORIZED=true
LDAP_STARTTLS=true
Always use secure connections in production. Set LDAP_TLS_REJECT_UNAUTHORIZED=false only for testing with self-signed certificates.
6

Password Length Override

LDAP servers handle their own password policies:
.env
MIN_PASSWORD_LENGTH=1
Setting this to 1 bypasses local password validation since LDAP handles authentication.

​
LDAP Strategy Implementation

The LDAP strategy (api/strategies/ldapStrategy.js) searches for users and creates/updates local records:
api/strategies/ldapStrategy.js
const ldapOptions = {
  server: {
    url: LDAP_URL,
    bindDN: LDAP_BIND_DN,
    bindCredentials: LDAP_BIND_CREDENTIALS,
    searchBase: LDAP_USER_SEARCH_BASE,
    searchFilter: LDAP_SEARCH_FILTER || 'mail={{username}}',
    searchAttributes: [...new Set(searchAttributes)],
  },
  usernameField: 'email',
  passwordField: 'password',
};

​
Active Directory Example

.env
LDAP_URL=ldap://dc.company.com:389
LDAP_BIND_DN=CN=Service Account,OU=Service Accounts,DC=company,DC=com
LDAP_BIND_CREDENTIALS=service-password
LDAP_USER_SEARCH_BASE=OU=Users,DC=company,DC=com
LDAP_SEARCH_FILTER=sAMAccountName={{username}}
LDAP_ID=objectGUID
LDAP_USERNAME=sAMAccountName
LDAP_EMAIL=mail
LDAP_FULL_NAME=displayName

​
OpenID Connect Authentication

OpenID Connect provides authentication through identity providers like Keycloak, Okta, or Azure AD.

​
Configuration

.env
OPENID_CLIENT_ID=your-client-id
OPENID_CLIENT_SECRET=your-client-secret
OPENID_ISSUER=https://your-idp.com/auth/realms/your-realm
OPENID_SESSION_SECRET=your-session-secret
OPENID_SCOPE="openid profile email"
OPENID_CALLBACK_URL=/oauth/openid/callback

​
Role-Based Access Control

.env
# Require specific role for access
OPENID_REQUIRED_ROLE=librechat-user
OPENID_REQUIRED_ROLE_TOKEN_KIND=access_token
OPENID_REQUIRED_ROLE_PARAMETER_PATH=realm_access.roles

# Define admin role
OPENID_ADMIN_ROLE=librechat-admin
OPENID_ADMIN_ROLE_PARAMETER_PATH=realm_access.roles
OPENID_ADMIN_ROLE_TOKEN_KIND=access_token

​
Custom Claim Mapping

.env
OPENID_USERNAME_CLAIM=preferred_username
OPENID_NAME_CLAIM=name
OPENID_EMAIL_CLAIM=email

​
Azure AD / Entra ID Example

.env
OPENID_CLIENT_ID=your-azure-app-id
OPENID_CLIENT_SECRET=your-azure-client-secret
OPENID_ISSUER=https://login.microsoftonline.com/your-tenant-id/v2.0
OPENID_SCOPE="openid profile email"
OPENID_EMAIL_CLAIM=upn
OPENID_CALLBACK_URL=/oauth/openid/callback

​
SAML Authentication

SAML authentication enables single sign-on with enterprise identity providers.

​
Configuration

The SAML strategy (api/strategies/samlStrategy.js) requires configuration through environment variables or a dedicated SAML configuration file.
SAML configuration is complex and typically requires coordination with your identity provider administrator.

​
Domain Restrictions

Restrict user registration to specific email domains using librechat.yaml:
librechat.yaml
registration:
  allowedDomains:
    - company.com
    - subsidiary.com

​
Security Best Practices

Follow these security guidelines for production deployments:
  • Always use HTTPS in production (DOMAIN_SERVER=https://...)
  • Generate cryptographically secure JWT secrets
  • Enable email verification (ALLOW_UNVERIFIED_EMAIL_LOGIN=false)
  • Use strong password requirements (MIN_PASSWORD_LENGTH=12 or higher)
  • Implement rate limiting for authentication endpoints
  • Regularly rotate JWT secrets and OAuth credentials
  • Use secure LDAP connections (LDAPS or StartTLS)
  • Restrict allowed email domains for registration
  • Enable two-factor authentication when available
  • Monitor authentication logs for suspicious activity

​
Troubleshooting

​
LDAP Connection Issues

# Test LDAP connection
ldapsearch -x -H ldap://ldap.example.com -D "cn=admin,dc=example,dc=com" -w password -b "dc=example,dc=com"

​
OAuth2 Redirect URI Mismatch

Ensure DOMAIN_SERVER matches your OAuth2 provider’s registered redirect URI:
.env
DOMAIN_SERVER=https://chat.example.com
GOOGLE_CALLBACK_URL=/oauth/google/callback
The full redirect URI will be: https://chat.example.com/oauth/google/callback

​
Email Verification Not Working

Check email service configuration and ensure ALLOW_UNVERIFIED_EMAIL_LOGIN is set appropriately: 
npm run create-user -- user@example.com "John Doe" johndoe --email-verified=true

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us