fix!: enforce OAuth state validation by default

`SSOBase.requires_state` defaulted to `False`, so the state validation added
in 0.19.0 never ran unless an integrator opted in. A callback carrying only a
`code` was accepted with nothing bound to the victim's session, allowing login
CSRF (CWE-352, CWE-1188).

`requires_state` now defaults to `True`, and a `state` present in the callback
is always matched against the `sso_state` cookie regardless of the flag, so a
state without a binding can no longer pass. The cookie is set `HttpOnly`,
`SameSite=lax` and `Secure` unless `allow_insecure_http` is enabled, and the
comparison is constant-time.

Reported by mohammad adnan (cystack.ps redteam) in GHSA-wgrh-7h2j-rg46.

BREAKING CHANGE: login flows that do not carry the `sso_state` cookie to the
callback now fail with `401 State cookie not found`. Set `requires_state` to
`False` on the instance to opt out, at the cost of CSRF protection.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018vc7GVDzhiJKacdr8cezuj

Author: autonomous-bot-agent-tomasvotava[bot]

README.md

@@ -38,6 +38,31 @@ Quick links for the eager ones:
 
 ## Security Notice
 
+### Version `0.22.0` Update: OAuth `state` Validation Is Now Enabled By Default
+
+The `state` validation added in `0.19.0` was gated behind `SSOBase.requires_state`, which defaulted to `False`.
+Applications that did not opt in performed no CSRF validation on the OAuth callback and remained vulnerable to
+login CSRF. This was reported by [@mohammedix88](https://github.com/mohammedix88) (cystack.ps redteam)
+in [GHSA-wgrh-7h2j-rg46](https://github.com/tomasvotava/fastapi-sso/security/advisories/GHSA-wgrh-7h2j-rg46).
+
+Since `0.22.0`, `requires_state` defaults to `True` and a `state` received in the callback is always matched against
+the `sso_state` cookie set at login time.
+
+**This is a breaking change.** A login flow that does not carry the `sso_state` cookie back to the callback now fails
+with `401 State cookie not found`. Two cases are affected:
+
+- The SSO instance is not used as a context manager (`async with sso:`), so no state is generated. This usage already
+  emitted a `SecurityWarning` and is now rejected at the callback.
+- The login and callback endpoints are served from different hosts, so the browser does not return the cookie.
+
+If you cannot carry the cookie across your deployment, you can opt out per instance, at the cost of losing CSRF
+protection:
+
+```python
+sso = GoogleSSO(client_id, client_secret, redirect_uri)
+sso.requires_state = False
+```
+
 ### Version `0.19.0` Update: OAuth `state` Validation Fix
 
 A critical OAuth login CSRF vulnerability caused by missing `state` validation was

docs/how-to-guides/state-return-url.md

@@ -9,8 +9,10 @@
     cryptographically random, stored server-side, and verified when the provider
     redirects the user back.
 
-    If you do **not** pass a `state` explicitly, `fastapi-sso` will generate, store,
-    and validate a secure random state for you.
+    If you do **not** pass a `state` explicitly, `fastapi-sso` generates a secure random
+    state for you, sets it as the `sso_state` cookie on the login redirect, and matches the
+    two when the provider calls back. This requires the SSO instance to be used as a context
+    manager (`async with sso:`) and the cookie to reach your callback endpoint.
 
     Using `state` to carry arbitrary user-controlled data (such as return URLs)
     **without validation** is unsafe and can lead to critical vulnerabilities

fastapi_sso/sso/base.py

@@ -4,6 +4,7 @@
 import json
 import logging
 import os
+import secrets
 import warnings
 from collections.abc import Callable
 from types import TracebackType
@@ -96,7 +97,7 @@ class SSOBase:
     scope: ClassVar[list[str]] = []
     additional_headers: ClassVar[dict[str, Any] | None] = None
     uses_pkce: bool = False
-    requires_state: bool = False
+    requires_state: bool = True
     use_id_token_for_user_info: ClassVar[bool] = False
     use_basic_auth: ClassVar[bool] = True
 
@@ -336,7 +337,13 @@ async def get_login_redirect(
         if self.uses_pkce:
             response.set_cookie("pkce_code_verifier", str(self._pkce_code_verifier))
         if state is not None:
-            response.set_cookie("sso_state", state)
+            response.set_cookie(
+                "sso_state",
+                state,
+                httponly=True,
+                samesite="lax",
+                secure=not self.allow_insecure_http,
+            )
         return response
 
     @overload
@@ -409,9 +416,9 @@ async def verify_and_process(
             raise SSOLoginError(400, "'state' parameter was not found in callback request")
         if self._state is not None:
             sso_state = request.cookies.get("sso_state")
-            if sso_state is None and self.requires_state:
+            if sso_state is None:
                 raise SSOLoginError(401, "State cookie not found")
-            if sso_state is not None and sso_state != self._state:
+            if not secrets.compare_digest(sso_state.encode(), self._state.encode()):
                 raise SSOLoginError(401, "Invalid state")
         pkce_code_verifier: str | None = None
         if self.uses_pkce:

fastapi_sso/sso/twitter.py

@@ -14,7 +14,6 @@ class TwitterSSO(SSOBase):
     provider = "twitter"
     scope: ClassVar = ["users.read", "tweet.read"]
     uses_pkce = True
-    requires_state = True
 
     async def get_discovery_document(self) -> DiscoveryDocument:
         return {

tests/test_base.py

@@ -48,8 +48,9 @@ async def test_not_implemented_ssobase(self):
         with pytest.raises(NotImplementedError):
             await sso.openid_from_token({})
 
-        request = Request()
+        request = Request(cookies={"sso_state": "state"})
         request.query_params["code"] = "code"
+        request.query_params["state"] = "state"
         with pytest.raises(NotImplementedError), pytest.warns(
             SecurityWarning, match="Please make sure you are using SSO provider in an async context"
         ):
@@ -76,7 +77,7 @@ class PostRequest:
             method = "POST"
             query_params = {}
             headers = {}
-            cookies = {}
+            cookies = {"sso_state": "state-from-form"}
             url = "http://localhost/auth/callback"
 
             @staticmethod

tests/test_providers_individual.py

@@ -82,7 +82,7 @@ class PostRequest:
         method = "POST"
         query_params = {}
         headers = {}
-        cookies = {}
+        cookies = {"sso_state": "state"}
         url = URL("https://localhost/auth/callback")
 
         @staticmethod

tests/test_state_validation.py

@@ -0,0 +1,96 @@
+# type: ignore
+
+import pytest
+from utils import Request
+
+from fastapi_sso.sso.base import DiscoveryDocument, OpenID, SSOBase, SSOLoginError
+from fastapi_sso.sso.google import GoogleSSO
+
+
+class FakeSSO(SSOBase):
+    provider = "fake"
+
+    async def get_discovery_document(self) -> DiscoveryDocument:
+        return {
+            "authorization_endpoint": "https://fake.com/authorize",
+            "token_endpoint": "https://fake.com/token",
+            "userinfo_endpoint": "https://fake.com/userinfo",
+        }
+
+    async def openid_from_response(self, response: dict, session=None) -> OpenID:
+        return OpenID(id="fake-id", provider=self.provider)
+
+
+@pytest.fixture()
+def sso(monkeypatch: pytest.MonkeyPatch) -> FakeSSO:
+    async def fake_process_login(self, code, request, **kwargs):
+        return "logged-in"
+
+    monkeypatch.setattr(SSOBase, "process_login", fake_process_login)
+    return FakeSSO("client_id", "client_secret", redirect_uri="https://localhost/callback")
+
+
+def callback(state: str | None = None, cookie: str | None = None) -> Request:
+    request = Request(cookies={"sso_state": cookie} if cookie is not None else None)
+    request.query_params["code"] = "code"
+    if state is not None:
+        request.query_params["state"] = state
+    return request
+
+
+@pytest.mark.parametrize("provider", [SSOBase, GoogleSSO])
+def test_state_is_required_by_default(provider: type[SSOBase]):
+    assert provider("client_id", "client_secret").requires_state is True
+
+
+async def test_callback_without_state_is_rejected(sso: FakeSSO):
+    async with sso:
+        with pytest.raises(SSOLoginError, match="'state' parameter was not found"):
+            await sso.verify_and_process(callback())
+
+
+async def test_callback_with_state_but_no_cookie_is_rejected(sso: FakeSSO):
+    async with sso:
+        with pytest.raises(SSOLoginError, match="State cookie not found"):
+            await sso.verify_and_process(callback(state="attacker-state"))
+
+
+async def test_callback_with_mismatched_cookie_is_rejected(sso: FakeSSO):
+    async with sso:
+        with pytest.raises(SSOLoginError, match="Invalid state"):
+            await sso.verify_and_process(callback(state="attacker-state", cookie="victim-state"))
+
+
+async def test_callback_with_non_ascii_state_is_rejected(sso: FakeSSO):
+    async with sso:
+        with pytest.raises(SSOLoginError, match="Invalid state"):
+            await sso.verify_and_process(callback(state="státe", cookie="state"))
+
+
+async def test_callback_with_matching_cookie_is_accepted(sso: FakeSSO):
+    async with sso:
+        assert await sso.verify_and_process(callback(state="state", cookie="state")) == "logged-in"
+
+
+async def test_state_validation_can_be_opted_out_of(sso: FakeSSO):
+    sso.requires_state = False
+    async with sso:
+        assert await sso.verify_and_process(callback()) == "logged-in"
+
+
+async def test_login_redirect_sets_hardened_state_cookie(sso: FakeSSO):
+    async with sso:
+        response = await sso.get_login_redirect()
+    cookie = response.headers["set-cookie"]
+    assert f"sso_state={sso._generated_state}" in cookie
+    assert "HttpOnly" in cookie
+    assert "Secure" in cookie
+    assert "SameSite=lax" in cookie
+
+
+async def test_state_cookie_is_not_secure_over_insecure_http(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("OAUTHLIB_INSECURE_TRANSPORT", raising=False)
+    sso = FakeSSO("client_id", "client_secret", redirect_uri="http://localhost/callback", allow_insecure_http=True)
+    async with sso:
+        response = await sso.get_login_redirect()
+    assert "Secure" not in response.headers["set-cookie"]

tests/utils.py

@@ -2,10 +2,11 @@
 
 
 class Request:
-    def __init__(self, url="http://localhost", query_params=None):
+    def __init__(self, url="http://localhost", query_params=None, cookies=None):
         self.url = URL(url)
         self.query_params = query_params or {}
         self.headers = {}
+        self.cookies = cookies or {}
 
 
 class Response: