Authentication Configuration LibreChat supports multiple authentication methods including email/password, OAuth2 social providers, OpenID Connect, SAML, and LDAP.
Registration and Login Settings Basic Authentication Controls Enable email/password authentication Allow new user registration ALLOW_REGISTRATION = true # Production (invite-only): ALLOW_REGISTRATION = false
Allow OAuth social login for existing users ALLOW_SOCIAL_REGISTRATION
Allow new user registration via social OAuth providers ALLOW_SOCIAL_REGISTRATION = false
Enable password reset functionality (requires email service) ALLOW_PASSWORD_RESET = false
Allow users to delete their own accounts ALLOW_ACCOUNT_DELETION = true
ALLOW_UNVERIFIED_EMAIL_LOGIN
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:
registration : socialLogins : [ 'github' , 'google' , 'discord' , 'openid' ] allowedDomains : - "company.com" - "partner.org"
OAuth2 Social Login 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
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
registration : socialLogins : [ 'google' ]
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
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 OAuth client secret
GITHUB_CALLBACK_URL
string
default: "/oauth/github/callback"
OAuth callback URL path
GITHUB_ENTERPRISE_BASE_URL
GitHub Enterprise server URL (optional)
GITHUB_ENTERPRISE_USER_AGENT
User agent for GitHub Enterprise (optional)
Discord OAuth Discord OAuth client ID DISCORD_CLIENT_ID = your-client-id
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 OAuth app ID FACEBOOK_CLIENT_ID = your-app-id
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 Sign In Apple service ID APPLE_CLIENT_ID = com.yourcompany.librechat
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 from your identity provider OPENID_CLIENT_ID = your-client-id
OpenID client secret OPENID_CLIENT_SECRET = your-client-secret
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
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 Claim to use for username (e.g., preferred_username, name) OPENID_USERNAME_CLAIM = preferred_username
Claim to use for display name Claim to use for email/identifier When not set, defaults to: email -> preferred_username -> upn # For Entra ID: OPENID_EMAIL_CLAIM = upn
Role-Based Access Control Required role for user access OPENID_REQUIRED_ROLE = LibreChat-User
OPENID_REQUIRED_ROLE_TOKEN_KIND
Token type for role claim (id_token or access_token) OPENID_REQUIRED_ROLE_TOKEN_KIND = access_token
OPENID_REQUIRED_ROLE_PARAMETER_PATH
JSON path to role claim in token OPENID_REQUIRED_ROLE_PARAMETER_PATH = realm_access.roles
Role that grants admin privileges OPENID_ADMIN_ROLE = LibreChat-Admin
OPENID_ADMIN_ROLE_PARAMETER_PATH
JSON path to admin role claim OPENID_ADMIN_ROLE_PARAMETER_PATH = realm_access.roles
OPENID_ADMIN_ROLE_TOKEN_KIND
Token type for admin role claim OPENID_ADMIN_ROLE_TOKEN_KIND = access_token
UI Customization Custom label for OpenID login button OPENID_BUTTON_LABEL = "Sign in with Azure AD"
Custom logo/icon URL for login button OPENID_IMAGE_URL = https://example.com/logo.png
Advanced Options Automatically redirect to OpenID provider on login page Only use if OpenID is your sole authentication method
OPENID_AUTO_REDIRECT = false
Use PKCE (Proof Key for Code Exchange) flow Optional audience parameter for authorization requests OPENID_AUDIENCE = https://api.example.com
Reuse OpenID tokens instead of MongoDB session OPENID_REUSE_TOKENS = false
OPENID_JWKS_URL_CACHE_ENABLED
Enable JWKS signing key cache OPENID_JWKS_URL_CACHE_ENABLED = true
OPENID_JWKS_URL_CACHE_TIME
JWKS cache duration in milliseconds (10 minutes default) OPENID_JWKS_URL_CACHE_TIME = 600000
OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED
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
Use OpenID Connect end session endpoint for logout OPENID_USE_END_SESSION_ENDPOINT = false
OPENID_POST_LOGOUT_REDIRECT_URI
URL to redirect to after OpenID logout Defaults to ${DOMAIN_CLIENT}/login OPENID_POST_LOGOUT_REDIRECT_URI = https://yourdomain.com/login
Microsoft Entra ID Integration USE_ENTRA_ID_FOR_PEOPLE_SEARCH
Enable Entra ID integration for people search USE_ENTRA_ID_FOR_PEOPLE_SEARCH = false
ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS
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
Enable SharePoint file picker (requires Entra ID) ENABLE_SHAREPOINT_FILEPICKER = true
SharePoint tenant base URL SHAREPOINT_BASE_URL = https://yourtenant.sharepoint.com
SHAREPOINT_PICKER_SHAREPOINT_SCOPE
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 identity provider entry point URL SAML_ENTRY_POINT = https://idp.example.com/saml/sso
SAML issuer (entity ID) SAML_ISSUER = https://yourdomain.com/saml/metadata
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
Secret for SAML session encryption # Generate with: openssl rand -hex 32 SAML_SESSION_SECRET = your-session-secret
SAML Attribute Mapping SAML attribute for email SAML_EMAIL_CLAIM = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
SAML attribute for username SAML_USERNAME_CLAIM = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
SAML attribute for first name SAML_GIVEN_NAME_CLAIM = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
SAML attribute for last name SAML_FAMILY_NAME_CLAIM = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
SAML attribute for profile picture URL SAML_PICTURE_CLAIM = picture
SAML attribute for display name SAML_NAME_CLAIM = displayName
SAML UI Customization Custom label for SAML login button SAML_BUTTON_LABEL = "Sign in with SSO"
Custom logo/icon URL for login button SAML_IMAGE_URL = https://example.com/logo.png
SAML_USE_AUTHN_RESPONSE_SIGNED
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 server URL LDAP_URL = ldap://ldap.example.com:389 # Or with TLS: LDAP_URL = ldaps://ldap.example.com:636
Bind DN for LDAP authentication LDAP_BIND_DN = cn = admin, dc = example, dc = com
Bind password for LDAP authentication LDAP_BIND_CREDENTIALS = your-bind-password
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 Path to CA certificate for TLS verification LDAP_CA_CERT_PATH = /path/to/ca-cert.pem
LDAP_TLS_REJECT_UNAUTHORIZED
Reject unauthorized TLS certificates LDAP_TLS_REJECT_UNAUTHORIZED = true
Use STARTTLS for encryption LDAP Attribute Mapping LDAP attribute for user ID (defaults to uid or sAMAccountName) LDAP attribute for username (defaults to givenName or mail) LDAP_USERNAME = sAMAccountName
LDAP attribute for email (defaults to mail) 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.Email Service Required for password reset functionality.
Configure SMTP email service: EMAIL_SERVICE = smtp EMAIL_HOST = smtp.gmail.com EMAIL_PORT = 587 EMAIL_ENCRYPTION = starttls EMAIL_USERNAME = [email protected] EMAIL_PASSWORD = your-app-password EMAIL_FROM = [email protected] EMAIL_FROM_NAME = "LibreChat"
Configure Mailgun API: MAILGUN_API_KEY = your-mailgun-api-key MAILGUN_DOMAIN = mg.yourdomain.com EMAIL_FROM = [email protected] EMAIL_FROM_NAME = "LibreChat" # For EU region: MAILGUN_HOST = https://api.eu.mailgun.net
SMTP server hostname EMAIL_HOST = smtp.gmail.com
Email encryption method (tls, starttls, or empty for none) EMAIL_ENCRYPTION = starttls
EMAIL_ENCRYPTION_HOSTNAME
Hostname for TLS certificate validation EMAIL_ENCRYPTION_HOSTNAME = smtp.gmail.com
Allow self-signed certificates EMAIL_ALLOW_SELFSIGNED = false
SMTP authentication username SMTP authentication password EMAIL_PASSWORD = your-app-password
Email “from” display name EMAIL_FROM_NAME = "LibreChat"
Complete Example Configurations
Azure AD (Entra ID) with OpenID
# 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"
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
# 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
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
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
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