[PR #1407] [MERGED] docs: correct the SSO, LDAP and SSO troubleshooting pages against oauth.py and auths.py #1372

New issue

Closed

opened 2026-10-18 14:19:13 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-18 14:19:13 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/open-webui/docs/pull/1407
Author: @silentoplayz
Created: 9/18/2026
Status: ✅ Merged
Merged: 9/18/2026
Merged by: @Classic298

Base: main ← Head: docs/auth-pages

📝 Commits (1)

2f11a58 docs: correct the SSO, LDAP and SSO troubleshooting pages against oauth.py and auths.py

📊 Changes

3 files changed (+33 additions, -30 deletions)

View changed files

📝 docs/features/authentication-access/auth/ldap.mdx (+8 -8)
📝 docs/features/authentication-access/auth/sso/index.mdx (+15 -14)
📝 docs/troubleshooting/sso.mdx (+10 -8)

📄 Description

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.

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.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/docs/pull/1407 **Author:** [@silentoplayz](https://github.com/silentoplayz) **Created:** 9/18/2026 **Status:** ✅ Merged **Merged:** 9/18/2026 **Merged by:** [@Classic298](https://github.com/Classic298) **Base:** `main` ← **Head:** `docs/auth-pages` --- ### 📝 Commits (1) - [`2f11a58`](https://github.com/open-webui/docs/commit/2f11a5827419c15c0172cc5282cc5a507ccb9508) docs: correct the SSO, LDAP and SSO troubleshooting pages against oauth.py and auths.py ### 📊 Changes **3 files changed** (+33 additions, -30 deletions) <details> <summary>View changed files</summary> 📝 `docs/features/authentication-access/auth/ldap.mdx` (+8 -8) 📝 `docs/features/authentication-access/auth/sso/index.mdx` (+15 -14) 📝 `docs/troubleshooting/sso.mdx` (+10 -8) </details> ### 📄 Description ## 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 - [x] I have reviewed the relevant documentation and matched the existing style. - [x] 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. - [x] 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`. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-18 14:19:13 +00:00