Skip to content

docs: correct the SSO, LDAP and SSO troubleshooting pages against oauth.py and auths.py - #1407

Merged
Classic298 merged 1 commit into
open-webui:mainfrom
silentoplayz:docs/auth-pages
Sep 18, 2026
Merged

Classic298 merged 1 commit into
open-webui:mainfrom
silentoplayz:docs/auth-pages

Conversation

@silentoplayz

Copy link
Copy Markdown
Collaborator

Summary

I compared the SSO overview, the SSO troubleshooting page and the LDAP page with utils/oauth.py, routers/auths.py, config.py and the admin Authentication settings on dev.

SSO overview:

  • WEBUI_URL is not what builds the redirect URI. The provider's *_REDIRECT_URI variable does, or the incoming request URL when that is unset. WEBUI_URL only decides where the browser is sent after the callback. The Microsoft and OIDC redirect variables are optional overrides, not requirements.
  • OPENID_PROVIDER_URL is no longer needed for Google or Microsoft sign-out. The discovery document is resolved from the provider the session was created with.
  • ENABLE_PROFILE_IMAGE_URL_FORWARDING does not govern SSO avatars: the login flow stores the IdP picture as a data URI. The picture is fetched with the access token during the callback, so it does not depend on a refresh token either.
  • Roles and groups are read from ID token claims and the userinfo response, never from the access token. OAUTH_ALLOWED_ROLES and OAUTH_ADMIN_ROLES have defaults, a non-matching role is refused with 403 rather than given the default role, the groups claim defaults to groups, an empty claim leaves memberships alone, and admins are synced like everyone else.
  • The trusted-header first-visit protection is the unique email constraint, not an email-derived id.

SSO troubleshooting: ENABLE_OAUTH is the master switch and ENABLE_OAUTH_SIGNUP is only for account creation, the OAuth handshake timeout is OAUTH_TIMEOUT (the OAuth client is httpx-based, so AIOHTTP_CLIENT_TIMEOUT does nothing for it), Microsoft does not need OPENID_PROVIDER_URL, and the callback error text varies by failure.

LDAP: the switch is labeled LDAP under Authentication, settings apply on the next login without a restart, new accounts get the instance default role (pending by default) with the first account becoming admin, the defaults for LDAP_USE_TLS and LDAP_VALIDATE_CERT are true, and StartTLS is not supported since LDAP_USE_TLS only opens implicit TLS.

Related issue or discussion

None.

Checklist

  • I have reviewed the relevant documentation and matched the existing style.
  • This PR meets Open WebUI's contribution standards: it is accurate, relevant to users, narrowly scoped, maintainable, and not promotional content, advertising, lead generation, SEO placement, or a request to list a product, service, provider, integration, gateway, tool, or company primarily for visibility.
  • I understand that PRs that do not meet these standards may be closed without review and will not be merged. Repeated, low-quality, off-topic, promotional, or intentionally misleading submissions may result in the contributor being blocked from future participation in Open WebUI repositories.

Notes for reviewers

Sources on dev: the redirect URI resolution and picture handling in utils/oauth.py, the role and group mapping there, the sign-out discovery resolution and the LDAP Server(...) construction in routers/auths.py, oauth_client_kwargs in config.py for the timeout, insert_new_auth in models/auths.py, and the LDAP section of Authentication.svelte.

@Classic298
Classic298 merged commit 69b0629 into open-webui:main Sep 18, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants