From f17eda26b89ac140c05ba0861e45ae5680518302 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Wed, 28 Oct 2026 19:35:52 +0100 Subject: [PATCH] docs(auth): explain OAuth configuration failures and Azure PKCE remediation Help administrators resolve confusing Microsoft PKCE errors by checking the redirect platform registration. Document the shared configuration error and provider classification hook used for safe user-facing failures. --- docs/backends/azuread.rst | 27 +++++++++++++++++++++++++++ docs/exceptions.rst | 18 +++++++++++++++++- 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index 853c0a0f..ab8997b5 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -537,3 +537,30 @@ local group synchronization. No separate extraction pipeline step is needed. .. _Microsoft access token claims reference: https://learn.microsoft.com/en-us/entra/identity-platform/access-token-claims-reference .. _Microsoft app role configuration: https://learn.microsoft.com/en-us/entra/identity-platform/howto-add-app-roles-in-apps .. _Microsoft scopes and permissions: https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc + +Troubleshooting PKCE requirements +--------------------------------- + +Microsoft error ``AADSTS9002325`` indicates that the request does not meet +Microsoft's PKCE requirements. The backend reports a configuration failure +(``invalid_setting``) and logs guidance to check the redirect platform registration. +Applications should direct users to their administrator rather than display +Microsoft's raw diagnostic description. + +In the Microsoft Entra admin center, open the app registration matching your +configured client ID and inspect its authentication platform settings. A callback +handled by your application's server belongs under the **Web** platform. +Registering it as a **Single-page application** (SPA) can trigger this error. +For Weblate, the callback path is +``/accounts/complete/azuread-tenant-oauth2/`` when using that backend. + +Check that the actual ``redirect_uri`` in the outgoing authorization request +exactly matches the registered external HTTPS callback, including its path and +trailing slash. When TLS terminates at a reverse proxy, verify the external URL +rather than relying only on internal request URLs in error reports. + +When enabling PKCE using the settings above, the authorization request must +include an S256 ``code_challenge`` and the token exchange must include its matching +``code_verifier``. Enabling PKCE alone does not correct a server callback registered +as an SPA. Correct the platform registration and start a fresh login attempt. +The backend does not change platform registrations or enable PKCE automatically. diff --git a/docs/exceptions.rst b/docs/exceptions.rst index e8c660ab..1683a023 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -233,7 +233,8 @@ HTTP status alone does not establish cancellation, expired credentials, or a local policy rejection. Shared HTTP handling retains status and structured provider codes. Unknown provider codes remain provider errors. -For OAuth, ``invalid_client`` is a configuration failure and ``invalid_grant`` +For OAuth, ``invalid_request`` and ``invalid_client`` are configuration failures +and ``invalid_grant`` is credential rejection. The latter does not establish expiry. Explicit ``access_denied`` indicates authorization refusal. HTTP 429 and server errors receive retry-later guidance; TLS verification failures require administrator @@ -312,3 +313,18 @@ confirmed expiry boundary with:: ) Do not translate that text into a code elsewhere in the application. + +Provider classification hook +---------------------------- + +Backends can override ``get_provider_error(data, *, stage="callback", +status_code=None, retry_after=None)`` to return a structured social-auth +exception or ``None``. The default uses the shared provider classifier. +OAuth2 callback errors and shared HTTP failures use this hook. Delegate unknown +errors to ``super()`` and preserve the operation stage and HTTP metadata. +Existing ``process_error()`` overrides continue to work. + +Azure AD logs fixed administrator guidance for ``AADSTS9002325`` without +including the raw provider description. The public error remains the shared +configuration failure ``invalid_setting``. See :doc:`backends/azuread` for +remediation.