Skip to main content

πŸ” 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, including https://.

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 β†’ Use OPENID_PROVIDER_URL instead
  • WEBUI_OIDC_CLIENT_ID β†’ Use OAUTH_CLIENT_ID instead
  • WEBUI_ENABLE_SSO β†’ Use ENABLE_OAUTH_SIGNUP instead
  • WEBUI_AUTH_TYPE β†’ This doesn't exist - configure provider-specific variables instead
  • OPENID_CLIENT_ID β†’ Use OAUTH_CLIENT_ID instead
  • OPENID_CLIENT_SECRET β†’ Use OAUTH_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:

  1. For Development/Testing: Set ENABLE_OAUTH_PERSISTENT_CONFIG=false to always read from environment variables
  2. 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 to true
  3. 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
    • 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
  • 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!
  • 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.


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
# 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 logs
  • CSRF 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:

  1. 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
  1. 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:

  1. Clear browser cookies and cache completely
  2. 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

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:

  1. Temporarily expose Open WebUI port directly
  2. Update OAuth provider redirect URI to point to direct port
  3. Test authentication without proxy
  4. 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 issue
  • httpcore.ReadTimeout β†’ Network timeout issue
  • The email or password provided is incorrect β†’ Often means OAuth completed but session wasn't established
  • 404 on callback URLs β†’ Redirect URI misconfiguration

Summary Checklist βœ…β€‹

ProblemFix
πŸ”— WebUI URL missing or wrongSet correct WebUI URL in admin panel
πŸ“ Env var typo or missingDouble-check against official docs - avoid non-existent vars like OIDC_CONFIG
🚨 Missing OPENID_PROVIDER_URLAlways required for OIDC - set to provider's .well-known/openid-configuration
πŸ”„ Persistent config conflictsSet ENABLE_OAUTH_PERSISTENT_CONFIG=false or use admin panel
🏒 Provider misconfiguredConfirm app registration, URIs & client IDs/secrets
🧊 Proxy caching interferingExclude OAuth endpoints from all server-side caches
πŸͺ Cookie configuration issuesCheck reverse proxy cookie settings and env vars
⏱️ Timeout problemsIncrease AIOHTTP_CLIENT_TIMEOUT values
πŸ” CSRF/session issuesVerify WEBUI_SECRET_KEY and session configuration
πŸ”€ Multi-instance problemsConfigure 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! 🦾