Authentication Configuration

LibreChat supports multiple authentication methods including email/password, OAuth2 social providers, OpenID Connect, SAML, and LDAP.

Basic Authentication Controls

Enable email/password authentication

ALLOW_EMAIL_LOGIN=true

ALLOW_REGISTRATION

boolean

default:"true"

Allow new user registration

ALLOW_REGISTRATION=true
# Production (invite-only):
ALLOW_REGISTRATION=false

Allow OAuth social login for existing users

ALLOW_SOCIAL_LOGIN=false

Allow new user registration via social OAuth providers

ALLOW_SOCIAL_REGISTRATION=false

ALLOW_PASSWORD_RESET

boolean

default:"false"

Enable password reset functionality (requires email service)

ALLOW_PASSWORD_RESET=false

ALLOW_ACCOUNT_DELETION

boolean

default:"true"

Allow users to delete their own accounts

ALLOW_ACCOUNT_DELETION=true

Allow login with unverified email addresses

ALLOW_UNVERIFIED_EMAIL_LOGIN=true
# Production:
ALLOW_UNVERIFIED_EMAIL_LOGIN=false

Domain Restrictions

Restrict registration to specific email domains using librechat.yaml:

librechat.yaml

registration:
  socialLogins: ['github', 'google', 'discord', 'openid']
  allowedDomains:
    - "company.com"
    - "partner.org"

LibreChat supports multiple OAuth2 providers for social login.

Google OAuth

Create OAuth App

Go to Google Cloud Console
Create a new project or select existing
Enable Google+ API
Go to Credentials > Create Credentials > OAuth client ID
Select Web application

Configure Redirect URIs

Add authorized redirect URI:

https://yourdomain.com/oauth/google/callback

Set Environment Variables

.env

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_CALLBACK_URL=/oauth/google/callback

# Enable social login
ALLOW_SOCIAL_LOGIN=true
ALLOW_SOCIAL_REGISTRATION=true

Enable in YAML

librechat.yaml

registration:
  socialLogins: ['google']

GOOGLE_CLIENT_ID

string

Google OAuth client ID

GOOGLE_CLIENT_SECRET

string

Google OAuth client secret

GOOGLE_CALLBACK_URL

string

default:"/oauth/google/callback"

OAuth callback URL path

GitHub OAuth

Create OAuth App

Go to GitHub Settings > Developer settings > OAuth Apps
Click New OAuth App
Fill in application details

Configure Callback URL

Set the callback URL:

https://yourdomain.com/oauth/github/callback

Set Environment Variables

.env

GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
GITHUB_CALLBACK_URL=/oauth/github/callback

# For GitHub Enterprise:
# GITHUB_ENTERPRISE_BASE_URL=https://github.enterprise.com
# GITHUB_ENTERPRISE_USER_AGENT=LibreChat

GITHUB_CLIENT_ID

string

GitHub OAuth client ID

GITHUB_CLIENT_SECRET

string

GitHub OAuth client secret

GITHUB_CALLBACK_URL

string

default:"/oauth/github/callback"

OAuth callback URL path

GITHUB_ENTERPRISE_BASE_URL

string

GitHub Enterprise server URL (optional)

GITHUB_ENTERPRISE_USER_AGENT

string

User agent for GitHub Enterprise (optional)

Discord OAuth

DISCORD_CLIENT_ID

string

Discord OAuth client ID

DISCORD_CLIENT_ID=your-client-id

DISCORD_CLIENT_SECRET

string

Discord OAuth client secret

DISCORD_CLIENT_SECRET=your-client-secret

DISCORD_CALLBACK_URL

string

default:"/oauth/discord/callback"

OAuth callback URL path

DISCORD_CALLBACK_URL=/oauth/discord/callback

Facebook OAuth

FACEBOOK_CLIENT_ID

string

Facebook OAuth app ID

FACEBOOK_CLIENT_ID=your-app-id

FACEBOOK_CLIENT_SECRET

string

Facebook OAuth app secret

FACEBOOK_CLIENT_SECRET=your-app-secret

FACEBOOK_CALLBACK_URL

string

default:"/oauth/facebook/callback"

OAuth callback URL path

FACEBOOK_CALLBACK_URL=/oauth/facebook/callback

APPLE_CLIENT_ID

string

Apple service ID

APPLE_CLIENT_ID=com.yourcompany.librechat

APPLE_TEAM_ID

string

Apple team ID

APPLE_TEAM_ID=XXXXXXXXX

APPLE_KEY_ID

string

Apple key ID

APPLE_KEY_ID=XXXXXXXXX

APPLE_PRIVATE_KEY_PATH

string

Path to Apple private key file

APPLE_PRIVATE_KEY_PATH=/path/to/AuthKey_XXXXXXXXX.p8

APPLE_CALLBACK_URL

string

default:"/oauth/apple/callback"

OAuth callback URL path

APPLE_CALLBACK_URL=/oauth/apple/callback

OpenID Connect

OpenID Connect (OIDC) provides SSO integration with enterprise identity providers like Azure AD, Keycloak, Okta, and Auth0.

Basic Configuration

OPENID_CLIENT_ID

string

required

OpenID client ID from your identity provider

OPENID_CLIENT_ID=your-client-id

OPENID_CLIENT_SECRET

string

required

OpenID client secret

OPENID_CLIENT_SECRET=your-client-secret

OPENID_ISSUER

string

required

OpenID provider issuer URL

# Azure AD:
OPENID_ISSUER=https://login.microsoftonline.com/{tenant-id}/v2.0

# Keycloak:
OPENID_ISSUER=https://keycloak.example.com/realms/myrealm

# Okta:
OPENID_ISSUER=https://dev-xxxxx.okta.com

# Auth0:
OPENID_ISSUER=https://your-tenant.auth0.com

OPENID_SESSION_SECRET

string

required

Secret for session encryption

# Generate with: openssl rand -hex 32
OPENID_SESSION_SECRET=your-session-secret

OPENID_SCOPE

string

default:"openid profile email"

OAuth scopes to request

OPENID_SCOPE="openid profile email"

OPENID_CALLBACK_URL

string

default:"/oauth/openid/callback"

Callback URL path

OPENID_CALLBACK_URL=/oauth/openid/callback

User Attribute Mapping

OPENID_USERNAME_CLAIM

string

Claim to use for username (e.g., preferred_username, name)

OPENID_USERNAME_CLAIM=preferred_username

OPENID_NAME_CLAIM

string

Claim to use for display name

OPENID_NAME_CLAIM=name

OPENID_EMAIL_CLAIM

string

Claim to use for email/identifierWhen not set, defaults to: email -> preferred_username -> upn

# For Entra ID:
OPENID_EMAIL_CLAIM=upn

Role-Based Access Control

OPENID_REQUIRED_ROLE

string

Required role for user access

OPENID_REQUIRED_ROLE=LibreChat-User

OPENID_REQUIRED_ROLE_TOKEN_KIND

string

Token type for role claim (id_token or access_token)

OPENID_REQUIRED_ROLE_TOKEN_KIND=access_token

OPENID_REQUIRED_ROLE_PARAMETER_PATH

string

JSON path to role claim in token

OPENID_REQUIRED_ROLE_PARAMETER_PATH=realm_access.roles

OPENID_ADMIN_ROLE

string

Role that grants admin privileges

OPENID_ADMIN_ROLE=LibreChat-Admin

OPENID_ADMIN_ROLE_PARAMETER_PATH

string

JSON path to admin role claim

OPENID_ADMIN_ROLE_PARAMETER_PATH=realm_access.roles

OPENID_ADMIN_ROLE_TOKEN_KIND

string

Token type for admin role claim

OPENID_ADMIN_ROLE_TOKEN_KIND=access_token

UI Customization

OPENID_BUTTON_LABEL

string

Custom label for OpenID login button

OPENID_BUTTON_LABEL="Sign in with Azure AD"

OPENID_IMAGE_URL

string

Custom logo/icon URL for login button

OPENID_IMAGE_URL=https://example.com/logo.png

Advanced Options

OPENID_AUTO_REDIRECT

boolean

default:"false"

Automatically redirect to OpenID provider on login page

Only use if OpenID is your sole authentication method

OPENID_AUTO_REDIRECT=false

OPENID_USE_PKCE

boolean

default:"false"

Use PKCE (Proof Key for Code Exchange) flow

OPENID_USE_PKCE=false

OPENID_AUDIENCE

string

Optional audience parameter for authorization requests

OPENID_AUDIENCE=https://api.example.com

OPENID_REUSE_TOKENS

boolean

default:"false"

Reuse OpenID tokens instead of MongoDB session

OPENID_REUSE_TOKENS=false

OPENID_JWKS_URL_CACHE_ENABLED

boolean

default:"true"

Enable JWKS signing key cache

OPENID_JWKS_URL_CACHE_ENABLED=true

OPENID_JWKS_URL_CACHE_TIME

number

default:"600000"

JWKS cache duration in milliseconds (10 minutes default)

OPENID_JWKS_URL_CACHE_TIME=600000

OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED

boolean

default:"false"

Trigger token exchange flow for userinfo endpoint

OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=false

OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE

string

default:"user.read"

Scope for on-behalf-of flow (Microsoft Graph API)

OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE="user.read"

OPENID_USE_END_SESSION_ENDPOINT

boolean

default:"false"

Use OpenID Connect end session endpoint for logout

OPENID_USE_END_SESSION_ENDPOINT=false

OPENID_POST_LOGOUT_REDIRECT_URI

string

URL to redirect to after OpenID logoutDefaults to ${DOMAIN_CLIENT}/login

OPENID_POST_LOGOUT_REDIRECT_URI=https://yourdomain.com/login

Microsoft Entra ID Integration

USE_ENTRA_ID_FOR_PEOPLE_SEARCH

boolean

default:"false"

Enable Entra ID integration for people search

USE_ENTRA_ID_FOR_PEOPLE_SEARCH=false

ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS

boolean

default:"false"

Include group owners as members in search results

ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS=false

OPENID_GRAPH_SCOPES

string

default:"User.Read,People.Read,GroupMember.Read.All"

Microsoft Graph API scopes for people/group search

OPENID_GRAPH_SCOPES=User.Read,People.Read,GroupMember.Read.All

SharePoint Integration

ENABLE_SHAREPOINT_FILEPICKER

boolean

default:"false"

Enable SharePoint file picker (requires Entra ID)

ENABLE_SHAREPOINT_FILEPICKER=true

SHAREPOINT_BASE_URL

string

SharePoint tenant base URL

SHAREPOINT_BASE_URL=https://yourtenant.sharepoint.com

SHAREPOINT_PICKER_SHAREPOINT_SCOPE

string

SharePoint scope for file picker

SHAREPOINT_PICKER_SHAREPOINT_SCOPE=https://yourtenant.sharepoint.com/AllSites.Read

SHAREPOINT_PICKER_GRAPH_SCOPE

string

default:"Files.Read.All"

Microsoft Graph scope for file picker

SHAREPOINT_PICKER_GRAPH_SCOPE=Files.Read.All

SAML

If OpenID is enabled, SAML authentication will be automatically disabled.

SAML_ENTRY_POINT

string

required

SAML identity provider entry point URL

SAML_ENTRY_POINT=https://idp.example.com/saml/sso

SAML_ISSUER

string

required

SAML issuer (entity ID)

SAML_ISSUER=https://yourdomain.com/saml/metadata

SAML_CERT

string

required

SAML identity provider certificate (base64 encoded)

SAML_CERT="MIIDXTCCAkWgAwIBAgIJAK..."

SAML_CALLBACK_URL

string

default:"/oauth/saml/callback"

SAML callback URL path

SAML_CALLBACK_URL=/oauth/saml/callback

SAML_SESSION_SECRET

string

required

Secret for SAML session encryption

# Generate with: openssl rand -hex 32
SAML_SESSION_SECRET=your-session-secret

SAML Attribute Mapping

SAML_EMAIL_CLAIM

string

SAML attribute for email

SAML_EMAIL_CLAIM=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

SAML_USERNAME_CLAIM

string

SAML attribute for username

SAML_USERNAME_CLAIM=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

SAML_GIVEN_NAME_CLAIM

string

SAML attribute for first name

SAML_GIVEN_NAME_CLAIM=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

SAML_FAMILY_NAME_CLAIM

string

SAML attribute for last name

SAML_FAMILY_NAME_CLAIM=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

SAML_PICTURE_CLAIM

string

SAML attribute for profile picture URL

SAML_PICTURE_CLAIM=picture

SAML_NAME_CLAIM

string

SAML attribute for display name

SAML_NAME_CLAIM=displayName

SAML UI Customization

SAML_BUTTON_LABEL

string

Custom label for SAML login button

SAML_BUTTON_LABEL="Sign in with SSO"

SAML_IMAGE_URL

string

Custom logo/icon URL for login button

SAML_IMAGE_URL=https://example.com/logo.png

SAML_USE_AUTHN_RESPONSE_SIGNED

boolean

default:"false"

Require entire SAML Response to be signed (not just Assertion)

SAML_USE_AUTHN_RESPONSE_SIGNED=false

LDAP

LDAP authentication integrates with Active Directory and other LDAP servers.

LDAP_URL

string

required

LDAP server URL

LDAP_URL=ldap://ldap.example.com:389
# Or with TLS:
LDAP_URL=ldaps://ldap.example.com:636

LDAP_BIND_DN

string

Bind DN for LDAP authentication

LDAP_BIND_DN=cn=admin,dc=example,dc=com

LDAP_BIND_CREDENTIALS

string

Bind password for LDAP authentication

LDAP_BIND_CREDENTIALS=your-bind-password

LDAP_USER_SEARCH_BASE

string

required

Base DN for user searches

LDAP_USER_SEARCH_BASE=ou=users,dc=example,dc=com

LDAP_SEARCH_FILTER

string

default:"mail={{username}}"

LDAP search filter template

LDAP_SEARCH_FILTER=mail={{username}}
# Active Directory:
LDAP_SEARCH_FILTER=sAMAccountName={{username}}

LDAP TLS/SSL

LDAP_CA_CERT_PATH

string

Path to CA certificate for TLS verification

LDAP_CA_CERT_PATH=/path/to/ca-cert.pem

LDAP_TLS_REJECT_UNAUTHORIZED

boolean

default:"true"

Reject unauthorized TLS certificates

LDAP_TLS_REJECT_UNAUTHORIZED=true

LDAP_STARTTLS

boolean

default:"false"

Use STARTTLS for encryption

LDAP_STARTTLS=false

LDAP Attribute Mapping

LDAP_ID

string

LDAP attribute for user ID (defaults to uid or sAMAccountName)

LDAP_ID=employeeNumber

LDAP_USERNAME

string

LDAP attribute for username (defaults to givenName or mail)

LDAP_USERNAME=sAMAccountName

LDAP_EMAIL

string

LDAP attribute for email (defaults to mail)

LDAP_EMAIL=mail

LDAP_FULL_NAME

string

Comma-separated list of LDAP attributes for full name

LDAP_FULL_NAME=givenName,sn
# Or use a single attribute:
LDAP_FULL_NAME=displayName

Use username field instead of email for login

LDAP_LOGIN_USES_USERNAME=true

LDAP Password Validation: When using LDAP, set MIN_PASSWORD_LENGTH=1 to bypass local password validation, as LDAP servers handle their own password policies.

MIN_PASSWORD_LENGTH=1

Email Service

Required for password reset functionality.

SMTP
Mailgun

Configure SMTP email service:

.env

EMAIL_SERVICE=smtp
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_ENCRYPTION=starttls
EMAIL_USERNAME=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
EMAIL_FROM=noreply@yourdomain.com
EMAIL_FROM_NAME="LibreChat"

Configure Mailgun API:

.env

MAILGUN_API_KEY=your-mailgun-api-key
MAILGUN_DOMAIN=mg.yourdomain.com
EMAIL_FROM=noreply@yourdomain.com
EMAIL_FROM_NAME="LibreChat"

# For EU region:
MAILGUN_HOST=https://api.eu.mailgun.net

EMAIL_SERVICE

string

Email service provider

EMAIL_SERVICE=smtp

EMAIL_HOST

string

SMTP server hostname

EMAIL_HOST=smtp.gmail.com

EMAIL_PORT

number

default:"25"

SMTP server port

EMAIL_PORT=587

EMAIL_ENCRYPTION

string

Email encryption method (tls, starttls, or empty for none)

EMAIL_ENCRYPTION=starttls

EMAIL_ENCRYPTION_HOSTNAME

string

Hostname for TLS certificate validation

EMAIL_ENCRYPTION_HOSTNAME=smtp.gmail.com

EMAIL_ALLOW_SELFSIGNED

boolean

default:"false"

Allow self-signed certificates

EMAIL_ALLOW_SELFSIGNED=false

EMAIL_USERNAME

string

SMTP authentication username

EMAIL_USERNAME=your-email@gmail.com

EMAIL_PASSWORD

string

SMTP authentication password

EMAIL_PASSWORD=your-app-password

EMAIL_FROM

string

default:"noreply@librechat.ai"

Email “from” address

EMAIL_FROM=noreply@yourdomain.com

EMAIL_FROM_NAME

string

Email “from” display name

EMAIL_FROM_NAME="LibreChat"

Complete Example Configurations

Azure AD (Entra ID) with OpenID

.env

# Basic configuration
OPENID_CLIENT_ID=your-application-id
OPENID_CLIENT_SECRET=your-client-secret
OPENID_ISSUER=https://login.microsoftonline.com/{tenant-id}/v2.0
OPENID_SESSION_SECRET=your-session-secret
OPENID_SCOPE="openid profile email"
OPENID_CALLBACK_URL=/oauth/openid/callback

# User mapping
OPENID_USERNAME_CLAIM=preferred_username
OPENID_NAME_CLAIM=name
OPENID_EMAIL_CLAIM=upn

# Role-based access
OPENID_REQUIRED_ROLE=LibreChat-User
OPENID_REQUIRED_ROLE_TOKEN_KIND=access_token
OPENID_REQUIRED_ROLE_PARAMETER_PATH=roles

# UI
OPENID_BUTTON_LABEL="Sign in with Microsoft"
OPENID_IMAGE_URL=https://www.microsoft.com/favicon.ico

# Enable social login
ALLOW_SOCIAL_LOGIN=true
ALLOW_SOCIAL_REGISTRATION=true

# Domain restrictions (in librechat.yaml)
# registration:
#   socialLogins: ['openid']
#   allowedDomains:
#     - "company.com"

Keycloak with OpenID

.env

OPENID_CLIENT_ID=librechat
OPENID_CLIENT_SECRET=your-client-secret
OPENID_ISSUER=https://keycloak.example.com/realms/myrealm
OPENID_SESSION_SECRET=your-session-secret
OPENID_SCOPE="openid profile email"
OPENID_CALLBACK_URL=/oauth/openid/callback

# Role mapping
OPENID_REQUIRED_ROLE=user
OPENID_REQUIRED_ROLE_TOKEN_KIND=access_token
OPENID_REQUIRED_ROLE_PARAMETER_PATH=realm_access.roles

OPENID_ADMIN_ROLE=admin
OPENID_ADMIN_ROLE_TOKEN_KIND=access_token
OPENID_ADMIN_ROLE_PARAMETER_PATH=realm_access.roles

# UI
OPENID_BUTTON_LABEL="Sign in with Keycloak"

ALLOW_SOCIAL_LOGIN=true
ALLOW_SOCIAL_REGISTRATION=true

Active Directory LDAP

.env

# LDAP connection
LDAP_URL=ldaps://ad.example.com:636
LDAP_BIND_DN=cn=LibreChat Service,ou=Service Accounts,dc=example,dc=com
LDAP_BIND_CREDENTIALS=your-service-account-password
LDAP_USER_SEARCH_BASE=ou=Users,dc=example,dc=com
LDAP_SEARCH_FILTER=sAMAccountName={{username}}

# TLS configuration
LDAP_CA_CERT_PATH=/path/to/ad-ca-cert.pem
LDAP_TLS_REJECT_UNAUTHORIZED=true

# Attribute mapping
LDAP_ID=objectGUID
LDAP_USERNAME=sAMAccountName
LDAP_EMAIL=mail
LDAP_FULL_NAME=displayName

# Use username for login
LDAP_LOGIN_USES_USERNAME=true

# Bypass local password validation
MIN_PASSWORD_LENGTH=1

# Allow LDAP login
ALLOW_EMAIL_LOGIN=true

# Domain restrictions (in librechat.yaml)
# registration:
#   allowedDomains:
#     - "example.com"

Troubleshooting

OAuth callback errors

Verify callback URLs match exactly in provider settings and .env
Check that DOMAIN_CLIENT and DOMAIN_SERVER are correctly configured
Ensure HTTPS is used in production
Verify OAuth app is enabled and approved

OpenID token errors

Check issuer URL is correct and accessible
Verify client ID and secret are correct
Ensure required scopes are granted in identity provider
Check token expiration and refresh token settings
Review JWKS cache settings if using custom configuration

LDAP connection issues

Verify LDAP URL is correct and server is accessible
Check bind DN and credentials are valid
Test LDAP connection using ldapsearch or similar tool
Verify user search base and search filter are correct
For TLS issues, check CA certificate path and hostname

Role-based access not working

Verify role claims are present in tokens (decode JWT)
Check role parameter path matches token structure
Ensure token kind (id_token vs access_token) is correct
Verify role names match exactly (case-sensitive)

Next Steps

File Storage

Configure S3, Firebase, or Azure storage

AI Endpoints

Set up AI provider endpoints

Environment Variables

Complete environment variable reference

YAML Configuration

Advanced YAML configuration

Documentation Index

​Authentication Configuration

​Registration and Login Settings

​Basic Authentication Controls

​Domain Restrictions

​OAuth2 Social Login

​Google OAuth

​GitHub OAuth

​Discord OAuth

​Facebook OAuth

​Apple Sign In

​OpenID Connect

​Basic Configuration

​User Attribute Mapping

​Role-Based Access Control

​UI Customization

​Advanced Options

​Microsoft Entra ID Integration

​SharePoint Integration

​SAML

​SAML Attribute Mapping

​SAML UI Customization

​LDAP

​LDAP TLS/SSL

​LDAP Attribute Mapping

​Email Service

​Complete Example Configurations

​Troubleshooting

​Next Steps

File Storage

AI Endpoints

Environment Variables

YAML Configuration

Authentication Configuration

Registration and Login Settings

Basic Authentication Controls

Domain Restrictions

OAuth2 Social Login

Google OAuth

GitHub OAuth

Discord OAuth

Facebook OAuth

Apple Sign In

OpenID Connect

Basic Configuration

User Attribute Mapping

Role-Based Access Control

UI Customization

Advanced Options

Microsoft Entra ID Integration

SharePoint Integration

SAML

SAML Attribute Mapping

SAML UI Customization

LDAP

LDAP TLS/SSL

LDAP Attribute Mapping

Email Service

Complete Example Configurations

Troubleshooting

Next Steps