Merge pull request #980 from semidark/cookie-based-auth

Add cookie‑based browser session auth for SharePoint Online (ClientContext.with_cookies)

Author: vgrem

.env.example

@@ -0,0 +1 @@
+export office365_python_sdk_securevars="{username};{password};{client_id};{client_secret}"\n

.github/workflows/python-app.yml

@@ -61,9 +61,13 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements.txt
           pip install -r requirements-dev.txt
-      - name: Test with pytest
+      - name: Test with pytest (skip entirely if secrets missing)
         env:
           office365_python_sdk_securevars: ${{ secrets.OFFICE365_PYTHON_SDK_SECUREVARS }}
         run: |
-          echo "${{env.office365_python_sdk_securevars}}"
-          pytest
+          if [ -z "${{env.office365_python_sdk_securevars}}" ]; then \
+            echo "No secrets available; skipping pytest"; \
+            exit 0; \
+          else \
+            pytest; \
+          fi

.gitignore

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

CONTRIBUTING.md

@@ -0,0 +1,184 @@
+## Welcome Contributors! 🎉
+
+Thank you for your interest in contributing to the Office365-REST-Python-Client library. This project provides a comprehensive Python client for Microsoft 365 and Microsoft Graph APIs.
+
+## Table of Contents
+
+1. Getting Started
+2. Development Environment Setup
+3. Code Style and Quality Standards
+4. Testing Guidelines
+5. Submitting Changes
+6. Issue Reporting
+7. Documentation
+8. Community Guidelines
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.6+
+- Git
+- A Microsoft 365 tenant for testing (recommended)
+- Basic understanding of REST APIs and Microsoft Graph/SharePoint APIs
+
+### Fork and Clone
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+
+```bash
+git clone https://github.com/your-username/Office365-REST-Python-Client.git
+cd Office365-REST-Python-Client
+```
+
+## Development Environment Setup
+
+### Virtual Environment
+
+```bash
+python3 -m venv venv
+. venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+### Install Dependencies
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+```
+
+### Pre-commit hooks (recommended)
+
+```bash
+pip install pre-commit
+pre-commit install
+pre-commit run -a
+```
+
+## Code Style and Quality Standards
+
+The project uses the following tools (mirroring CI):
+
+- Black (formatting)
+- Ruff (linting and import sorting)
+- Pylint (static analysis)
+
+Line length: 121 characters (configured in `pyproject.toml`).
+
+Run locally before pushing:
+
+```bash
+black .
+ruff check .
+pylint office365
+```
+
+## Testing Guidelines
+
+Most tests are end-to-end and require actual Microsoft 365 credentials.
+
+### Test Configuration
+
+1. Create a `.env` file in the project root:
+
+```bash
+export office365_python_sdk_securevars='{username};{password};{client_id};{client_secret}'
+```
+
+2. Source the environment file:
+
+```bash
+. .env
+```
+
+Note: The order of values is significant because tests parse by index.
+
+### Required Tenant Permissions
+
+For comprehensive testing, your test tenant should have these admin roles:
+
+- Global reader
+- Groups admin
+- Search admin
+- SharePoint admin
+- Teams service admin
+
+### Running Tests
+
+```bash
+pytest
+# or
+pytest -v
+# or a specific suite
+pytest tests/sharepoint/
+```
+
+CI note: Full E2E tests in CI rely on repository secrets and may not run on forks. Please run tests locally; maintainers trigger full CI runs as needed.
+
+### Forks and CI
+
+- Forked pull requests do not receive repository secrets. The CI pipeline will run formatting and linting, and it will skip `pytest` automatically if secrets are unavailable.
+- To validate your changes, run tests locally using your own tenant credentials as described above.
+- Maintainers will run the full E2E test suite on branches with access to secrets before merging.
+
+## Submitting Changes
+
+### Branching Strategy
+
+1. Create a feature branch from `master`:
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+2. Make your changes with clear, focused commits
+3. Ensure all tests pass and quality checks are satisfied
+
+### Pull Request Process
+
+1. CI Checks must pass:
+   - Ruff linting
+   - Black formatting
+   - Pylint analysis
+   - Pytest execution
+2. Await maintainer review
+3. Update documentation where applicable
+
+### Commit Guidelines
+
+- Use clear, descriptive commit messages
+- Reference issue numbers when applicable
+- Keep commits focused and atomic
+
+## Issue Reporting
+
+Before filing an issue:
+
+1. Search existing issues
+2. Check documentation and examples
+3. Test with the latest version
+
+Include in your report:
+
+- Environment: Python version, OS, library version
+- Reproduction: minimal code example
+- Expected vs Actual behavior
+- Authentication method used
+- Targeted service area (SharePoint, Graph, etc.)
+
+## Documentation
+
+### API Coverage
+
+The library supports multiple Microsoft 365 APIs, including SharePoint REST, Microsoft Graph, OneDrive, Outlook, Teams, OneNote, and Planner. See `examples/` for usage.
+
+## Community Guidelines
+
+This project is maintained by the community. Be respectful and constructive in all interactions.
+
+### License
+
+MIT License. By contributing, you agree that your contributions are licensed under these terms.
+
+

README-dev.md

@@ -15,7 +15,7 @@ So one has to configure his/her office/sharepoint credentials.
 To do so, create a file ```.env``` like this (replace the bracketed values by your values):
 
 ```
-export office365_python_sdk_securevars='{username};{password};{client_id};{client_password}'
+export office365_python_sdk_securevars='{username};{password};{client_id};{client_secret}'
 ```
 
 This file is in .gitignore, so it will never be committed.

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}")