Authentication Setup

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

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

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

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.

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.

.env

ALLOW_SOCIAL_LOGIN=true
ALLOW_SOCIAL_REGISTRATION=true

Google OAuth2

Create Google OAuth Credentials

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

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

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

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

Set LDAP Server URL

.env

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

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.

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

Configure Attribute Mapping

Map LDAP attributes to user fields:

.env

LDAP_ID=uid
LDAP_USERNAME=uid
LDAP_EMAIL=mail
LDAP_FULL_NAME=cn,displayName

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.

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

User Administration - Manage user accounts
Permissions - Configure role-based access control
Token Management - Manage user balances and credits

Get Started

Core Features

Configuration

Deployment

User Management

Authentication Setup

Authentication Strategies Overview

Local Email/Password Authentication

Configuration

Local Strategy Implementation

OAuth2 Authentication

Google OAuth2

GitHub OAuth2

Discord OAuth2

Facebook OAuth2

Apple OAuth2

LDAP Authentication

Prerequisites

Configuration

LDAP Strategy Implementation

Active Directory Example

OpenID Connect Authentication

Configuration

Role-Based Access Control

Custom Claim Mapping

Azure AD / Entra ID Example

SAML Authentication

Configuration

Domain Restrictions

Security Best Practices

Troubleshooting

LDAP Connection Issues

OAuth2 Redirect URI Mismatch

Email Verification Not Working

Next Steps

Get Started

Core Features

Configuration

Deployment

User Management

​Authentication Strategies Overview

​Local Email/Password Authentication

​Configuration

​Local Strategy Implementation

​OAuth2 Authentication

​Enable Social Login

​Google OAuth2

​GitHub OAuth2

​Discord OAuth2

​Facebook OAuth2

​Apple OAuth2

​LDAP Authentication

​Prerequisites

​Configuration

​LDAP Strategy Implementation

​Active Directory Example

​OpenID Connect Authentication

​Configuration

​Role-Based Access Control

​Custom Claim Mapping

​Azure AD / Entra ID Example

​SAML Authentication

​Configuration

​Domain Restrictions

​Security Best Practices

​Troubleshooting

​LDAP Connection Issues

​OAuth2 Redirect URI Mismatch

​Email Verification Not Working

​Next Steps

Authentication Strategies Overview

Local Email/Password Authentication

Configuration

Local Strategy Implementation

OAuth2 Authentication

Enable Social Login

Google OAuth2

GitHub OAuth2

Discord OAuth2

Facebook OAuth2

Apple OAuth2

LDAP Authentication

Prerequisites

Configuration

LDAP Strategy Implementation

Active Directory Example

OpenID Connect Authentication

Configuration

Role-Based Access Control

Custom Claim Mapping

Azure AD / Entra ID Example

SAML Authentication

Configuration

Domain Restrictions

Security Best Practices

Troubleshooting

LDAP Connection Issues

OAuth2 Redirect URI Mismatch

Email Verification Not Working

Next Steps