feat: add device code flow to GraphClient + example + update auth README

Author: Vadim

examples/auth/README.md

@@ -18,12 +18,15 @@ flowchart TD
 
     C --> G{User present to interact?}
     G -->|Yes| H[Interactive auth\nsupports MFA, SSO]
-    G -->|No, script or CI| I["ROPC (password grant)\nno MFA, legacy"]
+    G -->|No| I{Has a browser?}
+    I -->|Yes, visit URL| N[Device code flow\nheadless CLI, SSH,\nremote server]
+    I -->|No browser at all| O["ROPC (password grant)\nno MFA, legacy"]
 
     E --> J[with_certificate.py]
     F --> K[with_client_secret.py]
     H --> L[interactive.py]
-    I --> M[with_user_creds.py]
+    N --> P[with_device_flow.py]
+    O --> M[with_user_creds.py]
 
     style A fill:#1a73e8,color:#fff
     style B fill:#e8f0fe
@@ -43,6 +46,7 @@ flowchart TD
 | **Client secret** | `with_client_secret(client_id, secret)` | Daemons, cron jobs, CI/CD — app-only access | — | [`with_client_secret.py`](./with_client_secret.py) |
 | **Client certificate** | `with_certificate(client_id, thumbprint, key)` | Production daemons — app-only, no shared secret | — | [`with_client_cert.py`](./with_client_cert.py) |
 | **Interactive** | `with_token_interactive(client_id)` | Desktop apps, CLI tools — user signed-in | ✅ | [`interactive.py`](./interactive.py) |
+| **Device code** | `with_device_flow(client_id)` | Headless CLI, SSH, remote servers — user visits a URL | ✅ | [`with_device_flow.py`](./with_device_flow.py) |
 | **ROPC (password)** | `with_username_and_password(client_id, user, pass)` | Automated scripts — user context, no interactivity | ✗ | [`with_user_creds.py`](./with_user_creds.py) |
 | **National cloud** | `AzureEnvironment.USGovernmentHigh` | GCC High, DoD, China — applies to any flow above | varies | [`gcc_high.py`](./gcc_high.py) |
 

examples/auth/with_device_flow.py

@@ -0,0 +1,17 @@
+"""
+Device code flow authentication — ideal for CLI tools and headless
+environments without a web browser.
+
+The user authenticates by visiting a URL on another device (phone,
+laptop) and entering the displayed code. No interactive browser is
+needed on the machine running the script.
+
+https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code
+"""
+
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_tenant
+
+client = GraphClient(tenant=test_tenant).with_device_flow(test_client_id)
+me = client.me.get().execute_query()
+print(f"Authenticated as: {me.user_principal_name}")

office365/graph_client.py

@@ -171,6 +171,19 @@ def with_username_and_password(self, client_id: str, username: str, password: st
         self.pending_request().with_username_and_password(client_id, username, password)
         return self
 
+    def with_device_flow(self, client_id: str) -> Self:
+        """
+        Initialize with device code flow authentication.
+
+        Useful for CLI tools and headless environments. The user authenticates
+        by visiting a URL on another device and entering the displayed code.
+
+        Args:
+            client_id: Application client ID
+        """
+        self.pending_request().with_device_flow(client_id)
+        return self
+
     def with_transport(
         self,
         proxies: dict[str, str] | None = None,

office365/graph_request.py

@@ -110,6 +110,22 @@ def with_username_and_password(self, client_id: str, username: str, password: st
         self._auth_context.with_username_and_password(client_id, username, password)
         return self
 
+    def with_device_flow(self, client_id: str) -> GraphRequest:
+        """
+        Initialize with device code flow authentication.
+
+        Useful for CLI tools and headless environments. The user authenticates
+        by visiting a URL on another device and entering the displayed code.
+
+        Args:
+            client_id: The OAuth client ID of the calling application
+
+        Returns:
+            self: Supports fluent method chaining
+        """
+        self._auth_context.with_device_flow(client_id)
+        return self
+
     def authenticate_request(self, request: RequestOptions) -> None:
         """
         Authenticate the request by adding a bearer token.

office365/runtime/auth/entra/authentication_context.py

@@ -1,3 +1,4 @@
+import sys
 from typing import Any, Callable, Dict, List, Optional
 
 from typing_extensions import Self
@@ -46,6 +47,29 @@ def with_access_token(self, token_callback: Callable[[], Optional[Dict[str, Any]
         self._token_callback = token_callback
         return self
 
+    def with_device_flow(self, client_id: str) -> Self:
+        """Initializes the client via device code flow.
+
+        Useful for CLI tools and headless environments. The user authenticates
+        by visiting a URL on another device and entering the displayed code.
+
+        Args:
+            client_id: The OAuth client id of the calling application.
+        """
+        import msal
+
+        app = msal.PublicClientApplication(client_id, authority=self.authority_url)
+
+        def _acquire_token():
+            flow = app.initiate_device_flow(scopes=self._scopes)
+            if "user_code" not in flow:
+                raise ValueError(f"Failed to create device flow: {flow}")
+            print(flow["message"])
+            sys.stdout.flush()
+            return app.acquire_token_by_device_flow(flow)
+
+        return self.with_access_token(_acquire_token)
+
     def with_certificate(self, client_id: str, thumbprint: str, private_key: str):
         """Initializes the confidential client with client certificate