π Troubleshooting OAUTH / SSO Issues
OAUTH or Single Sign-On (SSO) lets you secure Open WebUI with modern authentication, but when users encounter login problems, the solution is often simpleβif you know where to look. Most of the time, one of these key issues below is the culprit. Here's how to hunt them down and fix SSO headaches fast! π¦
Common OAUTH/SSO Issues and How to Fix Them π οΈβ
1. WebUI URL Not Configured in Admin Panel πͺπβ
Most OAUTH flows require the application's external URL ("redirect URI") so the provider knows where to send users after login. If this is missing, OAUTH won't be able to complete!
β Solution:
- Navigate to: Admin Settings > General
- Ensure your WebUI URL field is filled in and points to your deployed instance (e.g.,
https://yourwebui.yourdomain.com
) π Tip: Check for typos! OAUTH is strictβURLs must match exactly, includinghttps://
.
2. Incorrect Environment Variable Configuration ππ«β
This is by far the most common cause of OAUTH breakage. If you misspell, omit, or set the wrong environment variable (especially for OIDC/OAUTH config), authentication can't work.
Common Environment Variable Mistakes:
β Non-Existent Variables People Often Use:β
OIDC_CONFIG
β UseOPENID_PROVIDER_URL
insteadWEBUI_OIDC_CLIENT_ID
β UseOAUTH_CLIENT_ID
insteadWEBUI_ENABLE_SSO
β UseENABLE_OAUTH_SIGNUP
insteadWEBUI_AUTH_TYPE
β This doesn't exist - configure provider-specific variables insteadOPENID_CLIENT_ID
β UseOAUTH_CLIENT_ID
insteadOPENID_CLIENT_SECRET
β UseOAUTH_CLIENT_SECRET
instead
β Correct OIDC Variables:β
# Required for OIDC
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret
OPENID_PROVIDER_URL=https://your-provider/.well-known/openid-configuration
ENABLE_OAUTH_SIGNUP=true
# Optional but recommended
OAUTH_PROVIDER_NAME=Your Provider Name
OAUTH_SCOPES=openid email profile
OPENID_REDIRECT_URI=https://your-domain/oauth/oidc/callback
β Correct Microsoft Variables:β
# Use these for Microsoft Entra ID
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret
MICROSOFT_CLIENT_TENANT_ID=your_tenant_id
OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration
ENABLE_OAUTH_SIGNUP=true
β Solutions:
- Always reference the official environment configuration documentation for exact variable names
- Double-check your deployment environment:
- Ensure all required environment variables are set exactly as documented
- If self-hosting, confirm these variables are present in your Docker Compose, Kubernetes manifest, or
.env
file
- Restart your backend/app after changing variables so the new values are loaded
π Tip: Most OAUTH errors (loops, 401s, unresponsiveness) are due to an environment variable incorrectly named, missing entirely, or using outdated variable names!
3. Missing Required Variables π¨β οΈβ
OPENID_PROVIDER_URL is Mandatory for OIDCβ
Many users forget this critical variable. Without it, OIDC authentication cannot work.
β For Microsoft Entra ID:
OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration
β For Google:
OPENID_PROVIDER_URL=https://accounts.google.com/.well-known/openid-configuration
β For Authentik:
OPENID_PROVIDER_URL=https://your-authentik-domain/application/o/your-app-name/.well-known/openid-configuration
Other Required Variables by Provider:β
- All OAuth providers:
WEBUI_URL
,ENABLE_OAUTH_SIGNUP=true
- Microsoft:
MICROSOFT_CLIENT_ID
,MICROSOFT_CLIENT_SECRET
,MICROSOFT_CLIENT_TENANT_ID
- Google:
GOOGLE_CLIENT_ID
,GOOGLE_CLIENT_SECRET
- OIDC:
OAUTH_CLIENT_ID
,OAUTH_CLIENT_SECRET
,OPENID_PROVIDER_URL
4. Persistent Configuration Conflicts ππΎβ
New Issue: Many users don't realize that OAuth settings are stored in the database after the first launch when ENABLE_OAUTH_PERSISTENT_CONFIG=true
(default).
Symptoms:β
- Changes to environment variables don't take effect after restart
- Authentication worked once but broke after configuration changes
- "No token found in localStorage" errors after reconfiguration
β Solutions:
- For Development/Testing: Set
ENABLE_OAUTH_PERSISTENT_CONFIG=false
to always read from environment variables - For Production: Either:
- Configure settings through Admin Panel instead of environment variables, OR
- Temporarily set
ENABLE_OAUTH_PERSISTENT_CONFIG=false
, restart to apply new env vars, then set back totrue
- Fresh Start: Delete the database volume and restart with correct configuration
π Example for Docker Compose:
environment:
- ENABLE_OAUTH_PERSISTENT_CONFIG=false # Forces reading from env vars
- OAUTH_CLIENT_ID=your_client_id
- OAUTH_CLIENT_SECRET=your_secret
- OPENID_PROVIDER_URL=your_provider_url
5. OAUTH Misconfiguration on the Provider Side π’πβ
Sometimes the issue is with the identity provider (e.g., Google, Okta, Auth0, Azure AD) not aligning with your WebUI's setup.
β Solutions:
- Verify your application is correctly registered with the OAUTH provider. Confirm:
- Redirect URIs exactly match your deployed WebUI address
- OIDC:
https://your-domain/oauth/oidc/callback
- Microsoft:
https://your-domain/oauth/microsoft/callback
- Google:
https://your-domain/oauth/google/callback
- OIDC:
- Client ID and secret match the values given in your environment settings
- Scopes and allowed grant types (e.g.,
authorization_code
) are set as required by Open WebUI
- Redirect URIs exactly match your deployed WebUI address
- Check the provider's logsβmisconfigured apps will often show clear error messages there
π Redirect URI Format Examples:
β
Correct: https://ai.company.com/oauth/oidc/callback
β Wrong: https://ai.company.com/oauth/callback/oidc
β Wrong: https://ai.company.com/callback
π Tip: When in doubt, recheck your provider registration and regenerate client secrets if needed.
6. Server-Side Caching (A Hidden Trouble Spot!) π§π¦β
A new and tricky problem: If you use NGINX (or another reverse proxy) with server-side caching, OAUTH endpoints can misbehave. The result isn't always a total failureβoften, users experience random or "weird" login bugs that are almost impossible to debug.
β Solutions:
- In your NGINX (or proxy) configuration:
- Make sure to exclude the following endpoints from server-side caching:
/api
,/oauth
,/callback
,/login
,/ws
,/websocket
- Any critical login/auth endpoint must remain uncached!
- Make sure to exclude the following endpoints from server-side caching:
- Reload the proxy config after making changes
Example NGINX Configuration:
# Disable caching for login / OAuth / websockets endpoints
location ~* ^/(api|oauth|callback|login|ws|websocket) {
proxy_no_cache 1;
proxy_cache_bypass 1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_set_header Accept-Encoding "";
}
π Warning: Never cache OAUTH or login endpoints! Caching can "poison" the session or deliver stale tokens, causing bizarre auth errors.
7. Cookie Configuration Issues πͺβοΈβ
Common Problem: Reverse proxy cookie settings can interfere with OAuth authentication, especially the HttpOnly
and SameSite
settings.
Symptoms:β
- "No token found in localStorage" errors
- Redirect loops after successful authentication
- Authentication works but immediately redirects to login page
β Solutions:
For NGINX Proxy Manager:β
# Remove or adjust problematic cookie settings
# β Problematic:
# proxy_cookie_path / "/; Secure; HttpOnly; SameSite=None";
# β
Better:
proxy_cookie_flags ~ secure samesite=lax;
# or remove cookie manipulation entirely
Environment Variable Cookie Settings:β
# Recommended cookie settings for OAuth
WEBUI_SESSION_COOKIE_SAME_SITE=lax
WEBUI_AUTH_COOKIE_SAME_SITE=lax
WEBUI_SESSION_COOKIE_SECURE=true # Set to false if using HTTP
WEBUI_AUTH_COOKIE_SECURE=true # Set to false if using HTTP
8. Network Timeout Issues β±οΈπβ
New Issue: OAuth providers may be slow to respond, causing timeout errors during the authentication handshake.
Symptoms:β
httpcore.ReadTimeout
errors in logsCSRF Warning! State not equal in request and response
errors- OAuth login fails intermittently
β Solutions:
# Increase OAuth timeouts
AIOHTTP_CLIENT_TIMEOUT=600 # Very high number is needed here, since model responses that take a lot of time also rely on this timeout variable (e.g. a model that is reasoning for 5+ minutes)
AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST=30
9. Session State Mismatch (CSRF Errors) πββ
Advanced Issue: Session cookies not being properly maintained across OAuth redirect flow.
Symptoms:β
CSRF Warning! State not equal in request and response
mismatching_state
errors in logs- Authentication appears successful but redirects to login
β Solutions:
- Check Cookie Domain Configuration:
# Ensure cookies are set for the correct domain
WEBUI_URL=https://your-exact-domain.com # Must match exactly - check if you have a different value set in the admin panel
- Session Configuration:
# Ensure session handling is properly configured
WEBUI_SECRET_KEY=your_very_secure_random_key_here
OAUTH_SESSION_TOKEN_ENCRYPTION_KEY=another_secure_key_here
10. Load Balancer and Multi-Instance Issues πβοΈβ
Enterprise Issue: In multi-instance deployments, OAuth sessions can fail if not properly synchronized.
Required Configuration for Clusters:β
# Redis for session synchronization (required for multi-instance)
REDIS_URL=redis://your-redis:6379/0
WEBSOCKET_REDIS_URL=redis://your-redis:6379/0
# Shared secrets across all instances
WEBUI_SECRET_KEY=same_on_all_instances
OAUTH_SESSION_TOKEN_ENCRYPTION_KEY=same_on_all_instances
# WebSocket support for clusters
ENABLE_WEBSOCKET_SUPPORT=true
WEBSOCKET_MANAGER=redis
11. Provider-Specific Configuration Issues π’πβ
Microsoft Entra ID Common Issues:β
Problem: Using generic OIDC variables instead of Microsoft-specific ones.
β Correct Microsoft Setup:
# Use Microsoft-specific variables, not generic OIDC
MICROSOFT_CLIENT_ID=your_azure_app_id
MICROSOFT_CLIENT_SECRET=your_azure_app_secret
MICROSOFT_CLIENT_TENANT_ID=your_tenant_id
MICROSOFT_OAUTH_SCOPE=openid email profile
MICROSOFT_REDIRECT_URI=https://your-domain/oauth/microsoft/callback
# Also required for a working Microsoft setup
OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration
ENABLE_OAUTH_SIGNUP=true
Authentik Common Issues:β
Problem: Incorrect provider URL format.
β Correct Authentik Setup:
OAUTH_CLIENT_ID=your_authentik_client_id
OAUTH_CLIENT_SECRET=your_authentik_client_secret
OPENID_PROVIDER_URL=https://your-authentik-domain/application/o/your-app-slug/.well-known/openid-configuration
OAUTH_PROVIDER_NAME=Authentik
OAUTH_SCOPES=openid email profile
π§ͺ Advanced Troubleshooting Tipsβ
Check Token Storage Methodβ
Recent versions of Open WebUI moved from URL-based tokens to cookie-based tokens. If you have authentication issues:
- Clear browser cookies and cache completely
- Check browser Developer Tools:
- Look for
oauth_session_id
cookie (new method) - Check for any
oauth_id_token
cookie (legacy method) - Verify cookies have correct domain and path settings
- Look for
Debugging OAuth Flowβ
Enable debug logging and trace the OAuth flow:
# Enable detailed logging
GLOBAL_LOG_LEVEL=DEBUG
# Check logs for these key steps:
# 1. GET /oauth/{provider}/login - Should return 302 redirect
# 2. User authenticates with provider
# 3. GET /oauth/{provider}/callback?code=... - Should return 200 or redirect
# 4. User should be logged in
Database Debuggingβ
Check if user accounts are being created:
# Access your container
docker exec -it your-openwebui-container sh
# Check if users are created (adjust path to your data directory)
ls -la /app/backend/data/
Test Without Reverse Proxyβ
If using a reverse proxy, test OAuth directly against Open WebUI:
- Temporarily expose Open WebUI port directly
- Update OAuth provider redirect URI to point to direct port
- Test authentication without proxy
- If it works, the issue is in your proxy configuration
π§ͺ Pro Tip: Always Check the Logsβ
- Look at backend logs and browser network errors. The first error usually points to the misconfiguration (redirect URI mismatch, missing/invalid variable, provider-side error, or caching).
- If unsure which side is the problem, try logging in from an incognito browser window and watch for any blocked or failed requests.
Key Log Messages to Watch For:β
OAuth callback error: mismatching_state
β Session/cookie issuehttpcore.ReadTimeout
β Network timeout issueThe email or password provided is incorrect
β Often means OAuth completed but session wasn't established404
on callback URLs β Redirect URI misconfiguration
Summary Checklist β β
Problem | Fix |
---|---|
π WebUI URL missing or wrong | Set correct WebUI URL in admin panel |
π Env var typo or missing | Double-check against official docs - avoid non-existent vars like OIDC_CONFIG |
π¨ Missing OPENID_PROVIDER_URL | Always required for OIDC - set to provider's .well-known/openid-configuration |
π Persistent config conflicts | Set ENABLE_OAUTH_PERSISTENT_CONFIG=false or use admin panel |
π’ Provider misconfigured | Confirm app registration, URIs & client IDs/secrets |
π§ Proxy caching interfering | Exclude OAuth endpoints from all server-side caches |
πͺ Cookie configuration issues | Check reverse proxy cookie settings and env vars |
β±οΈ Timeout problems | Increase AIOHTTP_CLIENT_TIMEOUT values |
π CSRF/session issues | Verify WEBUI_SECRET_KEY and session configuration |
π Multi-instance problems | Configure Redis and shared secrets |
Still stuck? | Check debug logs, test without proxy, verify provider setup |
By carefully configuring BOTH your OAuth provider and your WebUI environmentβand keeping critical login endpoints immune to cachingβyou'll eliminate nearly all SSO/OAuth login problems. Don't let a typo, missing variable, or a hidden cache block your users from seamless, secure AI access! π¦Ύ