feat(auth): implement cookie-based authentication for SharePoint Online

- Added `CookieAuthProvider` to handle authentication using browser-session cookies.
- Introduced `with_cookies` method in `AuthenticationContext`, `ClientContext`, and `SharePointRequest` for seamless integration.
- Added examples for loading cookies from Playwright's `storage_state.json` and using them in authentication.
- Updated documentation to include new authentication method and examples.

Author: Nico Thomaier

.gitignore

@@ -82,3 +82,9 @@ Pipfile.lock
 
 # Self signed certificates
 examples/*.pem
+
+# Playwright
+storage_state.json
+
+# Cursor
+.cursorignore

README.md

@@ -115,6 +115,29 @@ me = ctx.web.current_user.get().execute_query()
 print(me.login_name)
 ```
 
+#### 5. Browser session cookies (SharePoint Online)
+
+Authenticate using cookies from a real browser session (e.g., Playwright). No Azure AD app registration required.
+
+Usage:
+```python
+from office365.sharepoint.client_context import ClientContext
+
+def cookie_source():
+    # Return a dict with FedAuth/rtFa/SPOIDCRL values or an AuthCookies instance
+    return {"FedAuth": "...", "rtFa": "...", "SPOIDCRL": "..."}
+
+ctx = ClientContext("https://contoso.sharepoint.com/sites/demo").with_cookies(cookie_source, ttl_seconds=None)
+web = ctx.web.get().execute_query()
+print(web.title)
+```
+
+Example: [auth_cookies.py](examples/sharepoint/auth_cookies.py)
+
+Notes:
+- `ttl_seconds` is optional. Use it to periodically refresh cookies from your source if it’s cheap (e.g., file read).
+- Cookies are secrets. Do not log them; secure any storage (e.g., Playwright `storage_state.json`).
+
 ### Examples
 
 There are **two approaches** available to perform API queries:
@@ -158,6 +181,7 @@ json = json.loads(response.content)
 web_title = json['d']['Title']
 print("Web title: {0}".format(web_title))
 ```
+   Tip: You can also authenticate `SharePointRequest` with cookies using `with_cookies(cookie_source, ttl_seconds=None)`.
 
 For SharePoint-specific examples, see:  
 📌 **[SharePoint examples guide](examples/sharepoint/README.md)**  

examples/sharepoint/README.md

@@ -24,5 +24,13 @@ This directory contains examples for SharePoint REST API v1
 
 ###   Working with site  
 
+###  Authentication using browser session cookies
+- **Authenticate with cookies**: [`../auth_cookies.py`](../auth_cookies.py)
+  - Demonstrates loading `FedAuth`, `rtFa`, `SPOIDCRL` from Playwright `storage_state.json` and using `ClientContext.with_cookies(...)`.
+  - Optional `ttl_seconds` parameter can periodically refresh cookies from the source.
+- **Capture cookies with Playwright (optional)**: [`./auth/capture_cookies_with_playwright.py`](./auth/capture_cookies_with_playwright.py)
+  - Not a library dependency. Requires `pip install playwright` and `playwright install chromium`.
+  - Launches a browser to log in, then saves `storage_state.json` which can be consumed by the cookie auth example.
+
 ---
 

examples/sharepoint/auth/capture_cookies_with_playwright.py

@@ -0,0 +1,63 @@
+"""
+Acquire SharePoint Online browser-session cookies using Playwright and save them into
+storage_state.json (or a custom path), which can be consumed by examples/sharepoint/auth_cookies.py.
+
+Requirements (not installed by the library):
+  pip install playwright
+  playwright install chromium
+
+Usage:
+  SP_SITE_URL="https://contoso.sharepoint.com/sites/demo" \
+  PLAYWRIGHT_STORAGE_STATE="./storage_state.json" \
+  HEADLESS=false \
+  python examples/sharepoint/auth/capture_cookies_with_playwright.py
+
+Notes:
+- The script opens a browser window. Complete the Microsoft login (including MFA) manually.
+- After login, return to the terminal and press Enter to persist cookies.
+- The resulting storage_state.json can be used by auth_cookies.py.
+"""
+
+import os
+
+from playwright.sync_api import sync_playwright
+
+
+def main() -> None:
+    site_url = os.environ.get("SP_SITE_URL")
+    if not site_url:
+        raise SystemExit(
+            "SP_SITE_URL is required, e.g. https://contoso.sharepoint.com/sites/demo"
+        )
+
+    storage_state_path = os.environ.get(
+        "PLAYWRIGHT_STORAGE_STATE", "./storage_state.json"
+    )
+    headless_env = os.environ.get("HEADLESS", "false").lower()
+    headless = headless_env in ("1", "true", "yes")
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=headless)
+        context = browser.new_context()
+        page = context.new_page()
+        page.goto(site_url)
+        # Wait for network to be idle; login flow may redirect to Microsoft login pages
+        page.wait_for_load_state("networkidle")
+
+        print(
+            "\nA browser window is open. Complete the login (including MFA) if prompted."
+        )
+        input(
+            "When the SharePoint page is fully loaded and you are authenticated, press Enter here to continue..."
+        )
+
+        # Persist cookies and related state
+        context.storage_state(path=storage_state_path)
+        print(f"Saved Playwright storage state to: {storage_state_path}")
+
+        context.close()
+        browser.close()
+
+
+if __name__ == "__main__":
+    main()

examples/sharepoint/auth_cookies.py

@@ -0,0 +1,36 @@
+import json
+import os
+from typing import Dict
+
+from office365.sharepoint.client_context import ClientContext
+
+
+def load_cookies_from_storage_state(path: str) -> Dict[str, str]:
+    """Load cookies exported by Playwright storage_state.json and extract SPO cookies.
+
+    The library does not depend on Playwright; this is a helper to demonstrate usage.
+    """
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    cookies = {}
+    for c in data.get("cookies", []):
+        name = c.get("name")
+        if name in {"FedAuth", "rtFa", "SPOIDCRL"}:
+            cookies[name] = c.get("value", "")
+    return cookies
+
+
+if __name__ == "__main__":
+    site_url = os.environ.get(
+        "SP_SITE_URL", "https://contoso.sharepoint.com/sites/demo"
+    )
+    storage_state_path = os.environ.get(
+        "PLAYWRIGHT_STORAGE_STATE", "./storage_state.json"
+    )
+
+    def cookie_source():
+        return load_cookies_from_storage_state(storage_state_path)
+
+    ctx = ClientContext(site_url).with_cookies(cookie_source)
+    web = ctx.web.get().execute_query()
+    print(f"Web title: {web.title}")

office365/runtime/auth/authentication_context.py

@@ -8,6 +8,7 @@
 from office365.azure_env import AzureEnvironment
 from office365.runtime.auth.client_credential import ClientCredential
 from office365.runtime.auth.providers.acs_token_provider import ACSTokenProvider
+from office365.runtime.auth.providers.cookie_provider import CookieAuthProvider
 from office365.runtime.auth.providers.saml_token_provider import SamlTokenProvider
 from office365.runtime.auth.token_response import TokenResponse
 from office365.runtime.auth.user_credential import UserCredential
@@ -180,7 +181,6 @@ def with_access_token(self, token_func):
         """
 
         def _authenticate(request):
-
             request_time = datetime.now(timezone.utc)
 
             if self._cached_token is None or request_time > self._token_expires:
@@ -196,6 +196,23 @@ def _authenticate(request):
         self._authenticate = _authenticate
         return self
 
+    def with_cookies(self, cookie_source, ttl_seconds=None):
+        # type: (Any, Any) -> "AuthenticationContext"
+        """
+        Initializes authentication using browser-session cookies.
+
+        :param Any cookie_source: Callable returning Dict[str, str] or an AuthCookies instance.
+        :param Any ttl_seconds: Optional max age for cached cookies before reloading from source.
+        """
+        provider = CookieAuthProvider(cookie_source, ttl_seconds)
+
+        def _authenticate(request):
+            # type: (RequestOptions) -> None
+            provider.authenticate_request(request)
+
+        self._authenticate = _authenticate
+        return self
+
     def with_credentials(self, credentials):
         # type: (UserCredential | ClientCredential) -> "AuthenticationContext"
         """

office365/runtime/auth/providers/cookie_provider.py

@@ -0,0 +1,74 @@
+from datetime import datetime, timedelta, timezone
+from typing import Callable, Dict, Optional, Union
+
+from office365.runtime.auth.auth_cookies import AuthCookies
+from office365.runtime.auth.authentication_provider import AuthenticationProvider
+
+
+class CookieAuthProvider(AuthenticationProvider):
+    """Authentication provider that applies SharePoint Online browser-session cookies.
+
+    Accepts a cookie source callback or a prebuilt AuthCookies instance and sets
+    the HTTP "Cookie" header on outgoing requests. Optionally, a TTL can be supplied
+    to refresh cached cookies after a specified number of seconds.
+    """
+
+    def __init__(
+        self,
+        cookie_source: Union[Callable[[], Dict[str, str]], AuthCookies],
+        ttl_seconds: Optional[int] = None,
+    ) -> None:
+        super().__init__()
+        self._cookie_source = cookie_source
+        self._ttl_seconds = ttl_seconds
+        self._cached_auth_cookies: Optional[AuthCookies] = None
+        self._acquired_at: Optional[datetime] = None
+
+    def refresh(self) -> None:
+        """Clears the cached cookies so that the next request reacquires them."""
+        self._cached_auth_cookies = None
+        self._acquired_at = None
+
+    def _is_expired(self, now_utc: datetime) -> bool:
+        if self._cached_auth_cookies is None:
+            return True
+        if self._ttl_seconds is None:
+            return False
+        if self._acquired_at is None:
+            return True
+        return now_utc >= self._acquired_at + timedelta(seconds=self._ttl_seconds)
+
+    def _acquire_from_source(self) -> AuthCookies:
+        source = self._cookie_source
+        if callable(source):
+            result = source()
+            if isinstance(result, AuthCookies):
+                cookies = result
+            elif isinstance(result, dict):
+                cookies = AuthCookies(result)
+            else:
+                raise ValueError(
+                    "cookie_source must return Dict[str, str] or AuthCookies"
+                )
+        elif isinstance(source, AuthCookies):
+            cookies = source
+        else:
+            raise ValueError(
+                "cookie_source must be a Callable[[], Dict[str, str]] or AuthCookies"
+            )
+
+        if not cookies.is_valid:
+            raise ValueError("Provided cookies are not valid for SharePoint Online.")
+        return cookies
+
+    def _ensure_cookies_cached(self) -> None:
+        now_utc = datetime.now(timezone.utc)
+        if self._is_expired(now_utc):
+            cookies = self._acquire_from_source()
+            self._cached_auth_cookies = cookies
+            self._acquired_at = now_utc
+
+    def authenticate_request(self, request) -> None:
+        """Sets the Cookie header using cached or freshly acquired cookies."""
+        self._ensure_cookies_cached()
+        request.set_header("Cookie", self._cached_auth_cookies.cookie_header)

office365/sharepoint/client_context.py

@@ -185,6 +185,17 @@ def with_credentials(self, credentials):
         self.authentication_context.with_credentials(credentials)
         return self
 
+    def with_cookies(self, cookie_source, ttl_seconds=None):
+        # type: (object, object) -> Self
+        """
+        Initializes authentication using browser-session cookies.
+
+        :param object cookie_source: Callable returning Dict[str, str] or an AuthCookies instance.
+        :param object ttl_seconds: Optional max age for cached cookies before reloading from source.
+        """
+        self.authentication_context.with_cookies(cookie_source, ttl_seconds)
+        return self
+
     def execute_batch(self, items_per_batch=100, success_callback=None):
         # type: (int, Callable[[List[ClientObject|ClientResult]], None]) -> Self
         """

office365/sharepoint/request.py

@@ -49,6 +49,17 @@ def with_credentials(self, credentials):
         self._auth_context.with_credentials(credentials)
         return self
 
+    def with_cookies(self, cookie_source, ttl_seconds=None):
+        # type: (object, object) -> Self
+        """
+        Initializes authentication using browser-session cookies.
+
+        :param object cookie_source: Callable returning Dict[str, str] or an AuthCookies instance.
+        :param object ttl_seconds: Optional max age for cached cookies before reloading from source.
+        """
+        self._auth_context.with_cookies(cookie_source, ttl_seconds)
+        return self
+
     def with_client_certificate(
         self,
         tenant,